@highstate/backend-api 0.27.0 → 0.29.0

package/src/index.ts

@@ -1,37 +1,143 @@
 import type { Services } from "@highstate/backend"
 import { rm } from "node:fs/promises"
-import { InstanceServiceDefinition } from "@highstate/api/instance.v1"
-import { PanelServiceDefinition } from "@highstate/api/panel.v1"
-import { SecretServiceDefinition } from "@highstate/api/secret.v1"
-import { WorkerServiceDefinition } from "@highstate/api/worker.v1"
-import { createServer } from "nice-grpc"
-import { createInstanceService } from "./handlers/instance"
+import { createServer, type RequestListener, type Server } from "node:http"
+import { connectNodeAdapter } from "@connectrpc/connect-node"
+import {
+  InstanceStateService,
+  LibraryService,
+  OperationService,
+  PanelService,
+  ProjectModelService,
+  ProjectService,
+  SecretService,
+} from "@highstate/api/v1"
+import { WorkerService } from "@highstate/api/worker.v1"
+import { createInstanceStateService } from "./handlers/instance-state"
+import { createLibraryService } from "./handlers/library"
+import { createOperationService } from "./handlers/operation"
 import { createPanelService } from "./handlers/panel"
+import { createProjectService } from "./handlers/project"
+import { createProjectModelService } from "./handlers/project-model"
 import { createSecretService } from "./handlers/secret"
 import { createWorkerService } from "./handlers/worker"
-import { createErrorHandlingMiddleware } from "./shared"
+import { createErrorHandlingInterceptor } from "./shared"
 
-export async function startBackedApi(services: Services) {
-  const server = createServer()
-  server.use(createErrorHandlingMiddleware(services))
+export type BackendApiOptions = {
+  address?: string
+  workerSocketPath?: string
+}
+
+export type BackendApiHandlerOptions = {
+  requestPathPrefix?: string
+}
 
-  server.add(InstanceServiceDefinition, createInstanceService(services))
-  server.add(PanelServiceDefinition, createPanelService(services))
-  server.add(SecretServiceDefinition, createSecretService(services))
-  server.add(WorkerServiceDefinition, createWorkerService(services))
+export type BackendApi = {
+  address: string
+  shutdown(): Promise<void>
+}
+
+/**
+ * Creates a Node.js handler for the public Highstate Connect API.
+ *
+ * @param services The backend services used by the API handlers.
+ * @param options The API handler options.
+ * @returns A Node.js request listener serving the public API.
+ */
+export function createBackendApiHandler(
+  services: Services,
+  options: BackendApiHandlerOptions = {},
+): RequestListener {
+  return connectNodeAdapter({
+    interceptors: [createErrorHandlingInterceptor(services)],
+    requestPathPrefix: options.requestPathPrefix,
+    routes(router) {
+      router.service(InstanceStateService, createInstanceStateService(services))
+      router.service(LibraryService, createLibraryService(services))
+      router.service(OperationService, createOperationService(services))
+      router.service(PanelService, createPanelService(services))
+      router.service(ProjectModelService, createProjectModelService(services))
+      router.service(ProjectService, createProjectService(services))
+      router.service(SecretService, createSecretService(services))
+      router.service(WorkerService, createWorkerService(services))
+    },
+  })
+}
 
+/**
+ * Starts the public Highstate Connect API.
+ *
+ * @param services The backend services used by the API handlers.
+ * @param options The API listen and worker socket options.
+ * @returns The running API and its lifecycle controls.
+ */
+export async function startBackendApi(
+  services: Services,
+  options: BackendApiOptions = {},
+): Promise<BackendApi> {
   const uid = process.geteuid?.()
-  const sockPath = `/run/user/${uid}/highstate.sock`
+  const workerSocketPath = options.workerSocketPath ?? `/run/user/${uid}/highstate.sock`
+  const workerAddress = `unix:${workerSocketPath}`
+  const address = options.address ?? workerAddress
+  const addresses = address === workerAddress ? [workerAddress] : [workerAddress, address]
+  const handler = createBackendApiHandler(services)
+  const servers = addresses.map(() => createServer(handler))
 
   try {
-    await rm(sockPath, { force: true })
+    await rm(workerSocketPath, { force: true })
   } catch (error) {
     if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
       services.logger.error({ error }, "failed to remove existing socket file")
     }
   }
 
-  await server.listen(`unix:${sockPath}`)
-  services.workerManager.config.HIGHSTATE_WORKER_API_PATH = sockPath
-  services.logger.info(`api listening at %s`, sockPath)
+  try {
+    for (const [index, server] of servers.entries()) {
+      const serverAddress = addresses[index]!
+      await listen(server, serverAddress)
+      services.logger.info(`api listening at "%s"`, serverAddress)
+    }
+  } catch (error) {
+    await Promise.allSettled(servers.map(close))
+    await rm(workerSocketPath, { force: true })
+    throw new Error("Failed to start backend api", { cause: error })
+  }
+
+  services.workerManager.config.HIGHSTATE_WORKER_API_PATH = workerSocketPath
+
+  return {
+    address,
+    async shutdown() {
+      await Promise.all(servers.map(close))
+      await rm(workerSocketPath, { force: true })
+    },
+  }
+}
+
+async function listen(server: Server, address: string): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject)
+    server.once("listening", resolve)
+
+    if (address.startsWith("unix:")) {
+      server.listen(address.slice("unix:".length))
+      return
+    }
+
+    const url = new URL(address.includes("://") ? address : `http://${address}`)
+    server.listen(Number(url.port), url.hostname)
+  })
+}
+
+async function close(server: Server): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    server.close(error => {
+      if (error) {
+        reject(error)
+        return
+      }
+
+      resolve()
+    })
+    server.closeAllConnections()
+  })
 }

package/src/shared/api-error.ts

@@ -0,0 +1,42 @@
+import type { GenMessage } from "@bufbuild/protobuf/codegenv2"
+import { create, type Message } from "@bufbuild/protobuf"
+import { type Code, ConnectError } from "@connectrpc/connect"
+import { BadRequestSchema, ErrorInfoSchema } from "@highstate/api/v1"
+
+export type ApiFieldViolation = {
+  field: string
+  reason: string
+  description: string
+}
+
+type OutgoingDetail = { desc: GenMessage<Message>; value: Message }
+
+export function createApiError(options: {
+  message: string
+  code: Code
+  reason: string
+  metadata?: Record<string, string>
+  fieldViolations?: readonly ApiFieldViolation[]
+}): ConnectError {
+  const details: OutgoingDetail[] = [
+    {
+      desc: ErrorInfoSchema,
+      value: create(ErrorInfoSchema, {
+        reason: options.reason,
+        domain: "highstate.io",
+        metadata: options.metadata,
+      }),
+    },
+  ]
+
+  if (options.fieldViolations?.length) {
+    details.push({
+      desc: BadRequestSchema,
+      value: create(BadRequestSchema, {
+        fieldViolations: options.fieldViolations.map(violation => ({ ...violation })),
+      }),
+    })
+  }
+
+  return new ConnectError(options.message, options.code, undefined, details)
+}

package/src/shared/authentication.ts

@@ -1,21 +1,181 @@
-import type { ApiKey, Services } from "@highstate/backend"
-import { type CallContext, ServerError, Status } from "nice-grpc-common"
+import type {
+  ApiKey,
+  BackendApiKey,
+  BackendRequestContext,
+  ProjectRequestContext,
+  ResolvedPermissionGrant,
+  ResolvedPermissionRestriction,
+  ResolvedPermissions,
+  Services,
+} from "@highstate/backend"
+import type {
+  BackendPermission,
+  BackendPermissionRestriction,
+  ProjectPermission,
+  ProjectPermissionRestriction,
+} from "@highstate/backend/shared"
+import { Code, type HandlerContext } from "@connectrpc/connect"
+import { ProjectLockedError, ProjectNotFoundError } from "@highstate/backend/shared"
+import { createApiError } from "./api-error"
+import { parseBearerToken } from "./authorization-header"
 
-export async function authenticate(
+type ServiceAccountSubject = Extract<
+  ProjectRequestContext["subject"],
+  { type: "service-account" }
+> & { apiKeyId: string }
+
+type BackendAuthorizationContext = Omit<BackendRequestContext, "subject"> & {
+  subject: ServiceAccountSubject
+}
+
+type ProjectAuthorizationContext = Omit<ProjectRequestContext, "subject"> & {
+  subject: ServiceAccountSubject
+}
+
+export async function authenticateBackend(
   services: Services,
-  context: CallContext,
-): Promise<[projectId: string, apiKey: ApiKey]> {
-  const token = context.metadata.get("api-key")
-  if (!token) {
-    throw new ServerError(Status.UNAUTHENTICATED, "No API key provided")
+  context: HandlerContext,
+): Promise<BackendAuthorizationContext> {
+  const token = getBearerToken(context)
+  const apiKey = await services.apiKeyService.getBackendApiKeyByToken(token)
+  const roleBindings = await services.database.backend.serviceAccountBackendRoleBinding.findMany({
+    where: { serviceAccountId: apiKey.serviceAccountId },
+    include: { role: { select: { rules: true } } },
+  })
+
+  return {
+    realm: "backend",
+    subject: {
+      type: "service-account",
+      serviceAccountId: apiKey.serviceAccountId,
+      apiKeyId: apiKey.id,
+    },
+    permissions: resolveBackendPermissions(
+      roleBindings.flatMap(binding =>
+        binding.role.rules.map(rule => ({
+          permissions: rule.permissions,
+          restrictions: rule.restrictions ?? [],
+        })),
+      ),
+      apiKey.restrictionRules,
+    ),
   }
+}
 
-  const projectId = context.metadata.get("project-id")
+export async function authenticateProject(
+  services: Services,
+  request: { projectId: string },
+  context: HandlerContext,
+): Promise<ProjectAuthorizationContext> {
+  const projectId = request.projectId
   if (!projectId) {
-    throw new ServerError(Status.UNAUTHENTICATED, "No project ID provided")
+    throw createApiError({
+      message: "No project ID provided",
+      code: Code.InvalidArgument,
+      reason: "PROJECT_ID_REQUIRED",
+      fieldViolations: [
+        {
+          field: "project_id",
+          reason: "REQUIRED",
+          description: "The project ID is required",
+        },
+      ],
+    })
+  }
+
+  const project = await services.database.backend.project.findUnique({
+    where: { id: projectId },
+    select: { id: true },
+  })
+
+  if (!project) {
+    throw new ProjectNotFoundError(projectId)
+  }
+
+  if (!(await services.projectUnlockService.checkProjectUnlocked(projectId))) {
+    throw new ProjectLockedError(projectId)
   }
 
-  const apiKey = await services.apiKeyService.getApiKeyByToken(projectId, token)
+  const token = getBearerToken(context)
+  const apiKey = await services.apiKeyService.getProjectCredentialByToken(projectId, token)
+  const projectDatabase = await services.database.forProject(projectId)
+  const roleBindings = await projectDatabase.serviceAccountRoleBinding.findMany({
+    where: { serviceAccountId: apiKey.serviceAccountId },
+    include: { role: { select: { rules: true } } },
+  })
+
+  return {
+    realm: "project",
+    projectId,
+    subject: {
+      type: "service-account",
+      serviceAccountId: apiKey.serviceAccountId,
+      apiKeyId: apiKey.id,
+    },
+    permissions: resolveProjectPermissions(
+      roleBindings.flatMap(binding =>
+        binding.role.rules.map(rule => ({
+          permissions: rule.permissions,
+          restrictions: rule.restrictions ?? [],
+        })),
+      ),
+      apiKey.restrictionRules,
+    ),
+  }
+}
+
+function getBearerToken(context: HandlerContext): string {
+  return parseBearerToken(context.requestHeader.get("authorization"))
+}
+
+function resolveBackendPermissions(
+  grants: readonly {
+    permissions: readonly BackendPermission[]
+    restrictions: readonly BackendPermissionRestriction[]
+  }[],
+  restrictions: BackendApiKey["restrictionRules"],
+): ResolvedPermissions<BackendPermission, BackendPermissionRestriction> {
+  return resolvePermissions(grants, restrictions)
+}
+
+function resolveProjectPermissions(
+  grants: readonly {
+    permissions: readonly ProjectPermission[]
+    restrictions: readonly ProjectPermissionRestriction[]
+  }[],
+  restrictions: ApiKey["restrictionRules"],
+): ResolvedPermissions<ProjectPermission, ProjectPermissionRestriction> {
+  return resolvePermissions(grants, restrictions)
+}
+
+function resolvePermissions<TPermission extends string, TRestriction>(
+  grants: readonly {
+    permissions: readonly TPermission[]
+    restrictions: readonly ResolvedPermissionRestriction<TRestriction>[]
+  }[],
+  restrictions: readonly {
+    permissions: readonly TPermission[]
+    restrictions?: readonly ResolvedPermissionRestriction<TRestriction>[]
+  }[],
+): ResolvedPermissions<TPermission, TRestriction> {
+  const restrictionByPermission = new Map(
+    restrictions.flatMap(rule =>
+      rule.permissions.map(permission => [permission, rule.restrictions ?? []] as const),
+    ),
+  )
+  const permissions = new Map<TPermission, ResolvedPermissionGrant<TRestriction>[]>()
+  for (const grant of grants) {
+    for (const permission of grant.permissions) {
+      const keyRestrictions = restrictionByPermission.get(permission)
+      if (restrictions.length > 0 && !keyRestrictions) {
+        continue
+      }
+
+      const permissionGrants = permissions.get(permission) ?? []
+      permissionGrants.push({ restrictions: [...grant.restrictions, ...(keyRestrictions ?? [])] })
+      permissions.set(permission, permissionGrants)
+    }
+  }
 
-  return [projectId, apiKey]
+  return permissions
 }

package/src/shared/authorization-header.test.ts

@@ -0,0 +1,36 @@
+import { Code } from "@connectrpc/connect"
+import { describe, expect, it } from "vitest"
+import { parseBearerToken } from "./authorization-header"
+
+describe("parseBearerToken", () => {
+  it("accepts a case-insensitive Bearer scheme without normalizing the token", () => {
+    expect(parseBearerToken("Bearer hcp_key_secret")).toBe("hcp_key_secret")
+    expect(parseBearerToken("BEARER hcb_KEY_secret")).toBe("hcb_KEY_secret")
+  })
+
+  it.each([
+    null,
+    "",
+    "hcp_key_secret",
+    "Basic hcp_key_secret",
+    "Bearer",
+    "Bearer ",
+    "Bearer  token",
+    "Bearer token ",
+    " Bearer token",
+    "Bearer token value",
+    "Bearer\ttoken",
+    "Bearer\ntoken",
+    "Bearer token\n",
+    "Bearer token\u0000",
+    "Bearer token\u00a0value",
+    `Bearer ${"a".repeat(10_000)} value`,
+  ])("rejects malformed authorization header %s", authorization => {
+    expect(() => parseBearerToken(authorization)).toThrowError(
+      expect.objectContaining({
+        code: Code.Unauthenticated,
+        rawMessage: "Invalid authorization header",
+      }),
+    )
+  })
+})

package/src/shared/authorization-header.ts

@@ -0,0 +1,24 @@
+import { Code } from "@connectrpc/connect"
+import { createApiError } from "./api-error"
+
+/**
+ * Extracts a token from an HTTP Bearer authorization value.
+ *
+ * @param authorization The Authorization header value.
+ * @returns The unmodified Bearer token.
+ */
+export function parseBearerToken(authorization: string | null): string {
+  const match = /^Bearer ([^\s]+)$/i.exec(authorization ?? "")
+  if (
+    !match ||
+    [...match[1]!].some(character => character.charCodeAt(0) <= 0x1f || character === "\x7f")
+  ) {
+    throw createApiError({
+      message: "Invalid authorization header",
+      code: Code.Unauthenticated,
+      reason: "AUTHORIZATION_HEADER_INVALID",
+    })
+  }
+
+  return match[1]!
+}

package/src/shared/conversion.test.ts

@@ -0,0 +1,122 @@
+import { create } from "@bufbuild/protobuf"
+import { timestampDate } from "@bufbuild/protobuf/wkt"
+import { ComponentKind, InstanceSchema } from "@highstate/api/v1"
+import { describe, expect, it } from "vitest"
+import {
+  fromInstance,
+  toInstance,
+  toInstancePatch,
+  toNullableTimestamp,
+  toProjectModel,
+  toTimestamp,
+} from "./conversion"
+
+describe("resource conversion", () => {
+  it("converts instance dynamic values and references in both directions", () => {
+    const backend = {
+      id: "example.component.v1:main" as const,
+      kind: "unit" as const,
+      type: "example.component.v1" as const,
+      name: "main" as const,
+      args: { enabled: true, nested: { value: 1 } },
+      inputs: {
+        input: [{ instanceId: "example.source.v1:source" as const, output: "value" }],
+      },
+      position: { x: 10, y: 20 },
+    }
+
+    const api = toInstance(backend)
+
+    expect(api.$typeName).toBe("io.highstate.v1.Instance")
+    expect(api.kind).toBe(ComponentKind.UNIT)
+    expect(fromInstance(api)).toEqual({
+      ...backend,
+      hubInputs: {},
+      injectionInputs: [],
+    })
+  })
+
+  it("rejects an unspecified component kind", () => {
+    const instance = create(InstanceSchema, {
+      id: "example.component.v1:main",
+      type: "example.component.v1",
+      name: "main",
+    })
+
+    expect(() => fromInstance(instance)).toThrow("Component kind must be specified")
+  })
+
+  it("maps whole and nested position masks to backend patches", () => {
+    const instance = create(InstanceSchema, {
+      id: "example.component.v1:main",
+      kind: ComponentKind.UNIT,
+      type: "example.component.v1",
+      name: "main",
+      position: { x: 10, y: 20 },
+    })
+
+    expect(toInstancePatch(instance, ["position.x"])).toEqual({ position: { x: 10 } })
+    expect(toInstancePatch(instance, ["position"])).toEqual({ position: { x: 10, y: 20 } })
+    expect(toInstancePatch(create(InstanceSchema, instance), ["position"])).toEqual({
+      position: { x: 10, y: 20 },
+    })
+  })
+
+  it("clears a whole optional position", () => {
+    const instance = create(InstanceSchema, {
+      id: "example.component.v1:main",
+      kind: ComponentKind.UNIT,
+      type: "example.component.v1",
+      name: "main",
+    })
+
+    expect(toInstancePatch(instance, ["position"])).toEqual({ position: null })
+  })
+
+  it("converts valid and nullable dates", () => {
+    const date = new Date("2026-08-24T12:34:56.789Z")
+
+    expect(timestampDate(toTimestamp(date))).toEqual(date)
+    expect(toNullableTimestamp(null)).toBeUndefined()
+  })
+
+  it("rejects invalid dates", () => {
+    expect(() => toTimestamp(new Date(Number.NaN))).toThrow(
+      "Cannot convert invalid date to timestamp",
+    )
+  })
+
+  it("flattens requested virtual and ghost instances into the API project model", () => {
+    const instance = {
+      id: "example.component.v1:resident" as const,
+      kind: "unit" as const,
+      type: "example.component.v1" as const,
+      name: "resident" as const,
+    }
+    const model = toProjectModel({
+      instances: [instance],
+      virtualInstances: [
+        {
+          ...instance,
+          id: "example.component.v1:virtual",
+          name: "virtual",
+          parentId: instance.id,
+        },
+      ],
+      ghostInstances: [
+        {
+          ...instance,
+          id: "example.component.v1:ghost",
+          name: "ghost",
+        },
+      ],
+      hubs: [],
+    })
+
+    expect(model.instances.map(value => value.id)).toEqual([
+      "example.component.v1:resident",
+      "example.component.v1:virtual",
+      "example.component.v1:ghost",
+    ])
+  })
+})