@highstate/library 0.9.18 → 0.9.20

package/src/proxmox.ts

@@ -1,10 +1,17 @@
 import { defineEntity, defineUnit, z } from "@highstate/contract"
-import { checksumSchema, fileEntity, serverOutputs } from "./common"
-import { credentialsSchema, keyPairEntity } from "./ssh"
-import { l7EndpointEntity } from "./network"
+import {
+  checksumSchema,
+  fileEntity,
+  serverEntity,
+  serverOutputs,
+  vmSecrets,
+  vmSshArgs,
+} from "./common"
+import { ipv4PrefixSchema, ipv46Schema, l7EndpointEntity } from "./network"
+import * as ssh from "./ssh"
 
 export const clusterEntity = defineEntity({
-  type: "proxmox.cluster",
+  type: "proxmox.cluster.v1",
 
   schema: z.object({
     endpoint: l7EndpointEntity.schema,
@@ -17,7 +24,7 @@ export const clusterEntity = defineEntity({
     password: z.string().optional(),
     apiToken: z.string().optional(),
 
-    ssh: credentialsSchema.optional(),
+    ssh: ssh.connectionSchema.optional(),
   }),
 
   meta: {
@@ -26,7 +33,7 @@ export const clusterEntity = defineEntity({
 })
 
 export const imageEntity = defineEntity({
-  type: "proxmox.image",
+  type: "proxmox.image.v1",
 
   schema: z.object({
     id: z.string(),
@@ -37,8 +44,11 @@ export const imageEntity = defineEntity({
   },
 })
 
+/**
+ * The connection to an existing Proxmox cluster.
+ */
 export const connection = defineUnit({
-  type: "proxmox.connection",
+  type: "proxmox.connection.v1",
 
   args: {
     /**
@@ -73,18 +83,9 @@ export const connection = defineUnit({
     defaultDatastoreId: z.string().optional(),
 
     /**
-     * The username to use for SSH connections to the Proxmox nodes.
-     *
-     * By default, this is set to "root".
-     */
-    sshUser: z.string().default("root"),
-
-    /**
-     * The port to use for SSH connections to the Proxmox nodes.
-     *
-     * By default, this is set to 22.
+     * The SSH configuration to use for connecting to the Proxmox nodes.
      */
-    sshPort: z.number().default(22),
+    ssh: ssh.argsSchema.prefault({}),
   },
 
   secrets: {
@@ -110,29 +111,30 @@ export const connection = defineUnit({
       },
     },
 
-    /**
-     * The SSH password to use for connecting to the Proxmox nodes.
-     */
-    sshPassword: z.string().optional(),
+    ...ssh.secrets,
   },
 
   inputs: {
-    /**
-     * The key pair to use for SSH connections to the Proxmox nodes.
-     */
-    sshKeyPair: {
-      entity: keyPairEntity,
-      required: false,
-    },
+    ...ssh.inputs,
   },
 
   outputs: {
+    /**
+     * The Proxmox cluster.
+     */
     proxmoxCluster: clusterEntity,
+
+    /**
+     * The server representing the Proxmox API endpoint.
+     */
+    server: {
+      entity: serverEntity,
+      required: false,
+    },
   },
 
   meta: {
     title: "Proxmox Connection",
-    description: "The connection to an existing Proxmox cluster.",
     category: "Proxmox",
     icon: "simple-icons:proxmox",
     iconColor: "#e56901",
@@ -144,8 +146,11 @@ export const connection = defineUnit({
   },
 })
 
+/**
+ * The image to upload to a Proxmox cluster.
+ */
 export const image = defineUnit({
-  type: "proxmox.image",
+  type: "proxmox.image.v1",
 
   args: {
     /**
@@ -204,7 +209,6 @@ export const image = defineUnit({
 
   meta: {
     title: "Proxmox Image",
-    description: "The image to upload to a Proxmox cluster.",
     category: "Proxmox",
     icon: "simple-icons:proxmox",
     iconColor: "#e56901",
@@ -217,8 +221,11 @@ export const image = defineUnit({
   },
 })
 
+/**
+ * The existing image on a Proxmox cluster.
+ */
 export const existingImage = defineUnit({
-  type: "proxmox.existing-image",
+  type: "proxmox.existing-image.v1",
 
   args: {
     id: z.string(),
@@ -234,7 +241,6 @@ export const existingImage = defineUnit({
 
   meta: {
     title: "Proxmox Existing Image",
-    description: "The existing image on a Proxmox cluster.",
     category: "Proxmox",
     icon: "simple-icons:proxmox",
     iconColor: "#e56901",
@@ -247,8 +253,11 @@ export const existingImage = defineUnit({
   },
 })
 
+/**
+ * The virtual machine on a Proxmox cluster.
+ */
 export const virtualMachine = defineUnit({
-  type: "proxmox.virtual-machine",
+  type: "proxmox.virtual-machine.v1",
 
   args: {
     /**
@@ -282,35 +291,30 @@ export const virtualMachine = defineUnit({
          *
          * By default, this is set to 1.
          */
-        cores: z.number(),
+        cores: z.number().default(1),
 
         /**
          * The number of CPU sockets to allocate to the virtual machine.
          *
          * By default, this is set to 1.
          */
-        sockets: z.number(),
+        sockets: z.number().default(1),
 
         /**
          * The amount of dedicated memory to allocate to the virtual machine, in MB.
          *
          * By default, this is set to 512 MB.
          */
-        memory: z.number(),
+        memory: z.number().default(512),
 
         /**
          * The size of the disk to create for the virtual machine, in GB.
          *
          * By default, this is set to 8 GB.
          */
-        diskSize: z.number(),
+        diskSize: z.number().default(8),
       })
-      .default({
-        cores: 1,
-        sockets: 1,
-        memory: 512,
-        diskSize: 8,
-      }),
+      .prefault({}),
 
     /**
      * The IPv4 address configuration for the virtual machine.
@@ -326,21 +330,21 @@ export const virtualMachine = defineUnit({
           /**
            * The IPv4 address to assign to the virtual machine.
            */
-          address: z.string(),
+          address: z.ipv4(),
 
           /**
            * The CIDR prefix for the IPv4 address.
            *
            * By default, this is set to 24.
            */
-          prefix: z.number().default(24),
+          prefix: ipv4PrefixSchema.default(24),
 
           /**
            * The IPv4 gateway for the virtual machine.
            *
            * If not specified, will be set to the first address in the subnet.
            */
-          gateway: z.string().optional(),
+          gateway: z.ipv4().optional(),
         }),
       ])
       .default({ type: "dhcp" }),
@@ -353,37 +357,21 @@ export const virtualMachine = defineUnit({
         /**
          * The list of DNS servers to use for the virtual machine.
          */
-        dns: z.string().array(),
+        dns: ipv46Schema.array().default([]),
 
         /**
          * The name of the network bridge to connect the virtual machine to.
          *
          * By default, this is set to "vmbr0".
          */
-        bridge: z.string(),
+        bridge: z.string().default("vmbr0"),
       })
-      .default({ dns: [], bridge: "vmbr0" }),
+      .prefault({}),
 
     /**
      * The SSH configuration for the virtual machine.
      */
-    ssh: z
-      .object({
-        /**
-         * The port to use for SSH connections to the virtual machine.
-         *
-         * By default, this is set to 22.
-         */
-        port: z.number(),
-
-        /**
-         * The user to use for SSH connections to the virtual machine.
-         *
-         * By default, this is set to "root".
-         */
-        user: z.string(),
-      })
-      .default({ port: 22, user: "root" }),
+    ssh: vmSshArgs,
 
     /**
      * Whether to wait for the Proxmox agent to be ready before returning.
@@ -399,18 +387,13 @@ export const virtualMachine = defineUnit({
   },
 
   secrets: {
-    sshPassword: z.string().optional(),
+    ...vmSecrets,
   },
 
   inputs: {
     proxmoxCluster: clusterEntity,
     image: imageEntity,
 
-    sshKeyPair: {
-      entity: keyPairEntity,
-      required: false,
-    },
-
     /**
      * The cloud-init vendor data to use for the virtual machine.
      *
@@ -420,13 +403,14 @@ export const virtualMachine = defineUnit({
       entity: fileEntity,
       required: false,
     },
+
+    ...ssh.inputs,
   },
 
   outputs: serverOutputs,
 
   meta: {
     title: "Proxmox Virtual Machine",
-    description: "The virtual machine on a Proxmox cluster.",
     category: "Proxmox",
     icon: "simple-icons:proxmox",
     iconColor: "#e56901",
@@ -438,3 +422,6 @@ export const virtualMachine = defineUnit({
     path: "virtual-machine",
   },
 })
+
+export type Cluster = z.infer<typeof clusterEntity.schema>
+export type Image = z.infer<typeof imageEntity.schema>

package/src/restic.ts

@@ -2,7 +2,7 @@ import { defineEntity, defineUnit, z } from "@highstate/contract"
 import { l3EndpointEntity, l4EndpointEntity } from "./network"
 
 export const repositoryEntity = defineEntity({
-  type: "restic.repository",
+  type: "restic.repository.v1",
 
   schema: z.object({
     remoteEndpoints: z.union([l3EndpointEntity.schema, l4EndpointEntity.schema]).array(),
@@ -18,10 +18,20 @@ export const repositoryEntity = defineEntity({
   },
 })
 
-export const repo = defineUnit({
-  type: "restic.repo",
+/**
+ * Holds the configuration for a Restic repository and its remote storage.
+ */
+export const repository = defineUnit({
+  type: "restic.repository.v1",
 
   args: {
+    /**
+     * The remote endpoints of the cloud storage where the Restic repository will be stored.
+     *
+     * They will be used to create network policies to allow access to the storage.
+     *
+     * For some cloud providers, these endpoints can be automatically discovered.
+     */
     remoteEndpoints: z.string().array().default([]),
 
     /**
@@ -39,7 +49,7 @@ export const repo = defineUnit({
   },
 
   secrets: {
-    rcloneConfig: z.string(),
+    rcloneConfig: z.string().meta({ language: "ini" }),
   },
 
   inputs: {
@@ -61,7 +71,6 @@ export const repo = defineUnit({
 
   meta: {
     title: "Restic Repo",
-    description: "Holds the configuration for a Restic repository and its remote storage.",
     iconColor: "#e56901",
     icon: "material-symbols:backup",
     category: "Infrastructure",
@@ -69,7 +78,7 @@ export const repo = defineUnit({
 
   source: {
     package: "@highstate/restic",
-    path: "repo",
+    path: "repository",
   },
 })
 

package/src/sops.ts

@@ -1,12 +1,20 @@
 import { defineUnit, z } from "@highstate/contract"
-import { fileEntity } from "./files"
-import { serverEntity } from "./common"
+import { fileEntity } from "./common/files"
+import { serverEntity } from "./common/server"
 
+/**
+ * Encrypts secrets using SOPS for the specified servers.
+ */
 export const secrets = defineUnit({
-  type: "sops.secrets",
+  type: "sops.secrets.v1",
 
   secrets: {
-    data: z.record(z.string(), z.any()),
+    /**
+     * The content of the SOPS secrets file.
+     *
+     * Will take precedence over the `data` input.
+     */
+    data: z.record(z.string(), z.unknown()),
   },
 
   inputs: {
@@ -15,6 +23,10 @@ export const secrets = defineUnit({
       required: false,
       multiple: true,
     },
+    data: {
+      entity: fileEntity,
+      required: false,
+    },
   },
 
   outputs: {
@@ -23,7 +35,6 @@ export const secrets = defineUnit({
 
   meta: {
     title: "SOPS Secrets",
-    description: "Encrypts secrets using SOPS for the specified servers.",
     icon: "mdi:file-lock",
     category: "Secrets",
   },

package/src/ssh.ts

@@ -1,16 +1,36 @@
-import { defineEntity, defineUnit, z } from "@highstate/contract"
-import { l4EndpointEntity } from "./network"
-import { fileEntity } from "./files"
+import { $inputs, $secrets, defineEntity, defineUnit, z } from "@highstate/contract"
+import { fileEntity } from "./common/files"
+import { l4EndpointEntity, portSchema } from "./network"
 
 export const keyTypeSchema = z.enum(["ed25519"])
 
+/**
+ * The entity representing an SSH key pair.
+ */
 export const keyPairEntity = defineEntity({
-  type: "ssh.key-pair",
+  type: "ssh.key-pair.v1",
 
   schema: z.object({
+    /**
+     * The type of the SSH key.
+     *
+     * For now, only `ed25519` is supported.
+     */
     type: keyTypeSchema,
+
+    /**
+     * The fingerprint of the SSH key.
+     */
     fingerprint: z.string(),
+
+    /**
+     * The public key in OpenSSH format.
+     */
     publicKey: z.string(),
+
+    /**
+     * The private key in PEM format.
+     */
     privateKey: z.string(),
   }),
 
@@ -19,19 +39,97 @@ export const keyPairEntity = defineEntity({
   },
 })
 
-export const credentialsSchema = z.object({
+/**
+ * The schema for the SSH connection configuration.
+ *
+ * Contains enough information to connect to an SSH server.
+ */
+export const connectionSchema = z.object({
+  /**
+   * The list of L4 endpoints which can be used to connect to the SSH server.
+   */
   endpoints: l4EndpointEntity.schema.array(),
+
+  /**
+   * The host key of the SSH server which will be used to verify the server's identity.
+   */
   hostKey: z.string(),
+
+  /**
+   * The user to connect as.
+   */
   user: z.string(),
+
+  /**
+   * The password to use for authentication.
+   */
   password: z.string().optional(),
+
+  /**
+   * The SSH key pair to use for authentication.
+   */
   keyPair: keyPairEntity.schema.optional(),
 })
 
+export const argsSchema = z.object({
+  /**
+   * Whether the SSH is enabled on the server.
+   *
+   * If set to `false`, all SSH-related functionality will be disabled.
+   */
+  enabled: z.boolean().default(true),
+
+  /**
+   * The alternate host to connect to.
+   */
+  host: z.string().optional(),
+
+  /**
+   * The SSH port to connect to.
+   */
+  port: portSchema.default(22),
+
+  /**
+   * The SSH user to connect as.
+   */
+  user: z.string().default("root"),
+})
+
+export const secrets = $secrets({
+  /**
+   * The SSH private key in PEM format.
+   */
+  sshPrivateKey: z.string().optional().meta({ multiline: true }),
+
+  /**
+   * The SSH password to use for authentication.
+   */
+  sshPassword: z.string().optional(),
+})
+
+export const inputs = $inputs({
+  /**
+   * The SSH key pair to use for authentication.
+   */
+  sshKeyPair: {
+    entity: keyPairEntity,
+    required: false,
+  },
+})
+
+/**
+ * Holds the ED25519 SSH key pair and generates the private key if not provided.
+ */
 export const keyPair = defineUnit({
-  type: "ssh.key-pair",
+  type: "ssh.key-pair.v1",
 
   secrets: {
-    privateKey: z.string().optional(),
+    /**
+     * The SSH private key in PEM format.
+     *
+     * If not provided, a new key pair will be generated and stored.
+     */
+    privateKey: z.string().optional().meta({ multiline: true }),
   },
 
   outputs: {
@@ -41,7 +139,6 @@ export const keyPair = defineUnit({
 
   meta: {
     title: "SSH Key Pair",
-    description: "Holds the ED25519 SSH key pair and generates the private key if not provided.",
     category: "ssh",
     icon: "charm:key",
     iconColor: "#ffffff",
@@ -55,6 +152,7 @@ export const keyPair = defineUnit({
   },
 })
 
+export type Args = z.infer<typeof argsSchema>
 export type KeyType = z.infer<typeof keyTypeSchema>
-export type Credentials = z.infer<typeof credentialsSchema>
 export type KeyPair = z.infer<typeof keyPairEntity.schema>
+export type Connection = z.infer<typeof connectionSchema>

package/src/talos.ts

@@ -1,8 +1,8 @@
 import { defineEntity, defineUnit, z } from "@highstate/contract"
-import { clusterInputs, clusterOutputs, scheduleOnMastersPolicyArgs } from "./k8s"
+import { clusterInputs, clusterOutputs, scheduleOnMastersPolicyArgs } from "./k8s/shared"
 
 export const clusterEntity = defineEntity({
-  type: "talos.cluster",
+  type: "talos.cluster.v1",
 
   schema: z.object({
     clientConfiguration: z.string(),
@@ -17,8 +17,11 @@ export const clusterEntity = defineEntity({
 export const cniSchema = z.enum(["none", "cilium", "flannel"])
 export const csiSchema = z.enum(["none", "local-path-provisioner"])
 
+/**
+ * The Talos cluster created on top of the server.
+ */
 export const cluster = defineUnit({
-  type: "talos.cluster",
+  type: "talos.cluster.v1",
 
   args: {
     ...scheduleOnMastersPolicyArgs,
@@ -88,7 +91,6 @@ export const cluster = defineUnit({
 
   meta: {
     title: "Talos Cluster",
-    description: "A Kubernetes cluster managed by Talos.",
     category: "Talos",
     color: "#2d2d2d",
     icon: "simple-icons:talos",

package/src/third-party/cloudflare.ts

@@ -0,0 +1,59 @@
+import { defineUnit, z } from "@highstate/contract"
+import { providerEntity } from "../dns"
+
+export const providerDataSchema = z.object({
+  /**
+   * The zone ID of the Cloudflare zone.
+   */
+  zoneId: z.string(),
+
+  /**
+   * The API token for the Cloudflare account.
+   *
+   * The API key must have permissions to manage DNS records for exactly one zone.
+   * If multiple zones are specified, the unit will fail.
+   *
+   * The required permissions are:
+   * - `Zone:Read`
+   * - `Zone:DNS:Edit`
+   */
+  apiToken: z.string(),
+})
+
+/**
+ * The Cloudflare connection for a single zone.
+ */
+export const connection = defineUnit({
+  type: "cloudflare.connection.v1",
+
+  secrets: {
+    /**
+     * The API token for the Cloudflare account.
+     *
+     * The API key must have permissions to manage DNS records for exactly one zone.
+     * If multiple zones are specified, the unit will fail.
+     *
+     * The required permissions are:
+     * - `Zone.Zone:Read`
+     * - `Zone.DNS:Edit`
+     */
+    apiToken: z.string(),
+  },
+
+  outputs: {
+    dnsProvider: providerEntity,
+  },
+
+  meta: {
+    title: "Cloudflare Connection",
+    icon: "simple-icons:cloudflare",
+    category: "Cloudflare",
+  },
+
+  source: {
+    package: "@highstate/cloudflare",
+    path: "connection",
+  },
+})
+
+export type ProviderData = z.infer<typeof providerDataSchema>

package/src/third-party/index.ts

@@ -0,0 +1,4 @@
+export * as cloudflare from "./cloudflare"
+export * as mullvad from "./mullvad"
+export * as timeweb from "./timeweb"
+export * as yandex from "./yandex"

package/src/{mullvad.ts → third-party/mullvad.ts}

@@ -1,9 +1,12 @@
 import { defineUnit, z } from "@highstate/contract"
-import { networkEntity, peerEntity } from "./wireguard"
-import { l4EndpointEntity } from "./network"
+import { l4EndpointEntity } from "../network"
+import { networkEntity, peerEntity } from "../wireguard"
 
+/**
+ * The Mullvad WireGuard peer fetched from the Mullvad API.
+ */
 export const peer = defineUnit({
-  type: "mullvad.peer",
+  type: "mullvad.peer.v1",
 
   args: {
     hostname: z.string().optional(),
@@ -37,7 +40,6 @@ export const peer = defineUnit({
 
   meta: {
     title: "Mullvad Peer",
-    description: "The Mullvad WireGuard peer fetched from the Mullvad API.",
     icon: "simple-icons:mullvad",
     secondaryIcon: "cib:wireguard",
     secondaryIconColor: "#88171a",