@highstate/library 0.9.16 → 0.9.19

package/src/wireguard.ts

@@ -1,35 +1,64 @@
-import { defineEntity, defineUnit, Type, type Static, type TObject } from "@highstate/contract"
+import { defineEntity, defineUnit, z } from "@highstate/contract"
 import { omit } from "remeda"
-import { clusterEntity, interfaceEntity, exposableWorkloadEntity } from "./k8s"
+import { serverEntity } from "./common/server"
+import { exposableWorkloadEntity, networkInterfaceEntity } from "./k8s"
 import { l3EndpointEntity, l4EndpointEntity } from "./network"
+import { clusterEntity } from "./k8s"
 import { arrayPatchModeSchema } from "./utils"
 
-export const backendSchema = Type.StringEnum(["wireguard", "amneziawg"])
+export const backendSchema = z.enum(["wireguard", "amneziawg"])
 
-export type Backend = Static<typeof backendSchema>
+export type Backend = z.infer<typeof backendSchema>
 
+const networkArgs = {
+  /**
+   * The backend to use for the WireGuard network.
+   *
+   * Possible values are:
+   * - `wireguard` - the default backend;
+   * - `amneziawg` - the censorship-resistant fork of WireGuard.
+   */
+  backend: backendSchema.default("wireguard"),
+
+  /**
+   * Whether to enable IPv4 support in the network.
+   *
+   * By default, IPv4 support is enabled.
+   */
+  ipv4: z.boolean().default(true),
+
+  /**
+   * Whether to enable IPv6 support in the network.
+   *
+   * By default, IPv6 support is disabled.
+   */
+  ipv6: z.boolean().default(false),
+}
+
+/**
+ * The entity representing the WireGuard network configuration.
+ *
+ * It holds shared configuration for WireGuard identities, peers, and nodes.
+ */
 export const networkEntity = defineEntity({
-  type: "wireguard.network",
+  type: "wireguard.network.v1",
 
-  schema: Type.Object({
-    backend: backendSchema,
-    ipv6: Type.Boolean(),
-  }),
+  schema: z.object(networkArgs),
 })
 
-export const nodeExposePolicySchema = Type.StringEnum(["always", "when-has-endpoint", "never"])
+export const nodeExposePolicySchema = z.enum(["always", "when-has-endpoint", "never"])
 
 export const peerEntity = defineEntity({
-  type: "wireguard.peer",
+  type: "wireguard.peer.v1",
 
-  schema: Type.Object({
-    name: Type.String(),
-    network: Type.Optional(networkEntity.schema),
-    publicKey: Type.String(),
-    address: Type.Optional(Type.String()),
-    allowedIps: Type.Array(Type.String()),
-    endpoints: Type.Array(l4EndpointEntity.schema),
-    allowedEndpoints: Type.Array(Type.Union([l3EndpointEntity.schema, l4EndpointEntity.schema])),
+  schema: z.object({
+    name: z.string(),
+    network: networkEntity.schema.optional(),
+    publicKey: z.string(),
+    address: z.string().optional(),
+    allowedIps: z.string().array(),
+    endpoints: l4EndpointEntity.schema.array(),
+    allowedEndpoints: z.union([l3EndpointEntity.schema, l4EndpointEntity.schema]).array(),
 
     /**
      * The pre-shared key of the WireGuard peer.
@@ -38,18 +67,18 @@ export const peerEntity = defineEntity({
      *
      * Will be ignored if both peers have `presharedKeyPart` set.
      */
-    presharedKey: Type.Optional(Type.String()),
+    presharedKey: z.string().optional(),
 
     /**
      * The pre-shared key part of the WireGuard peer.
      *
      * If both peers have `presharedKeyPart` set, their `presharedKey` will be calculated as XOR of the two parts.
      */
-    presharedKeyPart: Type.Optional(Type.String()),
+    presharedKeyPart: z.string().optional(),
 
-    excludedIps: Type.Array(Type.String()),
-    dns: Type.Array(Type.String()),
-    listenPort: Type.Optional(Type.Number()),
+    excludedIps: z.string().array(),
+    dns: z.string().array(),
+    listenPort: z.number().optional(),
   }),
 
   meta: {
@@ -58,11 +87,11 @@ export const peerEntity = defineEntity({
 })
 
 export const identityEntity = defineEntity({
-  type: "wireguard.identity",
+  type: "wireguard.identity.v1",
 
-  schema: Type.Object({
+  schema: z.object({
     peer: peerEntity.schema,
-    privateKey: Type.String(),
+    privateKey: z.string(),
   }),
 
   meta: {
@@ -70,45 +99,26 @@ export const identityEntity = defineEntity({
   },
 })
 
-export type Network = Static<typeof networkEntity.schema>
-export type Identity = Static<typeof identityEntity.schema>
-export type Peer = Static<typeof peerEntity.schema>
-export type NodeExposePolicy = Static<typeof nodeExposePolicySchema>
+export type Network = z.infer<typeof networkEntity.schema>
+export type Identity = z.infer<typeof identityEntity.schema>
+export type Peer = z.infer<typeof peerEntity.schema>
+export type NodeExposePolicy = z.infer<typeof nodeExposePolicySchema>
 
 /**
- * The network hols the shared configuration for the WireGuard identities, peers and nodes.
+ * Holds the shared configuration for WireGuard identities, peers, and nodes.
  */
 export const network = defineUnit({
-  type: "wireguard.network",
-
-  args: {
-    /**
-     * The backend to use for the WireGuard network.
-     *
-     * Possible values are:
-     * 1. `wireguard` - The default backend.
-     * 2. `amneziawg` - The censorship-resistant fork of WireGuard.
-     *
-     * By default, the `wireguard` backend is used.
-     */
-    backend: Type.Default(backendSchema, "wireguard"),
+  type: "wireguard.network.v1",
 
-    /**
-     * The option to enable IPv6 support in the network.
-     *
-     * By default, IPv6 support is disabled.
-     */
-    ipv6: Type.Default(Type.Boolean(), false),
-  },
+  args: networkArgs,
 
   outputs: {
     network: networkEntity,
   },
 
   meta: {
-    description: "The WireGuard network with some shared configuration.",
-    primaryIcon: "simple-icons:wireguard",
-    primaryIconColor: "#88171a",
+    icon: "simple-icons:wireguard",
+    iconColor: "#88171a",
     secondaryIcon: "mdi:local-area-network-connect",
     category: "VPN",
   },
@@ -125,32 +135,32 @@ const sharedPeerArgs = {
    *
    * If not provided, the peer will be named after the unit.
    */
-  peerName: Type.Optional(Type.String()),
+  peerName: z.string().optional(),
 
   /**
    * The address of the WireGuard interface.
    *
    * The address may be any IPv4 or IPv6 address. CIDR notation is also supported.
    */
-  address: Type.Optional(Type.String()),
+  address: z.string().optional(),
 
   /**
    * The convenience option to set `allowedIps` to `0.0.0.0/0, ::/0`.
    *
    * Will be merged with the `allowedIps` if provided.
    */
-  exitNode: Type.Default(Type.Boolean(), false),
+  exitNode: z.boolean().default(false),
 
   /**
    * The list of IP ranges to exclude from the tunnel.
    *
    * Implementation notes:
    *
-   * - This list will not be used to generate the allowed IPs for the peer.
-   * - Instead, the node will setup extra direct routes to these IPs via default gateway.
-   * - This allows to use `0.0.0.0/0, ::/0` in the `allowedIps` (and corresponding fwmark magic) and still have some IPs excluded from the tunnel.
+   * - this list will not be used to generate the allowed IPs for the peer;
+   * - instead, the node will setup extra direct routes to these IPs via default gateway;
+   * - this allows to use `0.0.0.0/0, ::/0` in the `allowedIps` (and corresponding fwmark magic) and still have some IPs excluded from the tunnel.
    */
-  excludedIps: Type.Default(Type.Array(Type.String()), []),
+  excludedIps: z.string().array().default([]),
 
   /**
    * The convenience option to exclude private IPs from the tunnel.
@@ -168,38 +178,38 @@ const sharedPeerArgs = {
    *
    * Will be merged with `excludedIps` if provided.
    */
-  excludePrivateIps: Type.Default(Type.Boolean(), false),
+  excludePrivateIps: z.boolean().default(false),
 
   /**
    * The endpoints of the WireGuard peer.
    */
-  endpoints: Type.Default(Type.Array(Type.String()), []),
+  endpoints: z.string().array().default([]),
 
   /**
    * The allowed endpoints of the WireGuard peer.
    *
    * The non `hostname` endpoints will be added to the `allowedIps` of the peer.
    */
-  allowedEndpoints: Type.Default(Type.Array(Type.String()), []),
+  allowedEndpoints: z.string().array().default([]),
 
   /**
    * The DNS servers that should be used by the interface connected to the WireGuard peer.
    *
    * If multiple peers define DNS servers, the node will merge them into a single list (but this is discouraged).
    */
-  dns: Type.Default(Type.Array(Type.String()), []),
+  dns: z.string().array().default([]),
 
   /**
    * The convenience option to include the DNS servers to the allowed IPs.
    *
    * By default, is `true`.
    */
-  includeDns: Type.Default(Type.Boolean(), true),
+  includeDns: z.boolean().default(true),
 
   /**
    * The port to listen on.
    */
-  listenPort: Type.Optional(Type.Number()),
+  listenPort: z.number().optional(),
 }
 
 const sharedPeerInputs = {
@@ -272,10 +282,24 @@ const sharedPeerOutputs = {
   },
 } as const
 
-export type SharedPeerArgs = Static<TObject<typeof sharedPeerArgs>>
+export type SharedPeerArgs = {
+  peerName?: string
+  address?: string
+  exitNode: boolean
+  excludedIps: string[]
+  excludePrivateIps: boolean
+  endpoints: string[]
+  allowedEndpoints: string[]
+  dns: string[]
+  includeDns: boolean
+  listenPort?: number
+}
 
+/**
+ * The WireGuard peer with the public key.
+ */
 export const peer = defineUnit({
-  type: "wireguard.peer",
+  type: "wireguard.peer.v1",
 
   args: {
     ...sharedPeerArgs,
@@ -283,23 +307,22 @@ export const peer = defineUnit({
     /**
      * The public key of the WireGuard peer.
      */
-    publicKey: Type.String(),
+    publicKey: z.string(),
   },
 
   secrets: {
     /**
      * The pre-shared key which should be used for the peer.
      */
-    presharedKey: Type.Optional(Type.String()),
+    presharedKey: z.string().optional(),
   },
 
   inputs: sharedPeerInputs,
   outputs: sharedPeerOutputs,
 
   meta: {
-    description: "The WireGuard peer with the public key.",
-    primaryIcon: "simple-icons:wireguard",
-    primaryIconColor: "#88171a",
+    icon: "simple-icons:wireguard",
+    iconColor: "#88171a",
     secondaryIcon: "mdi:badge-account-horizontal",
     category: "VPN",
   },
@@ -310,14 +333,17 @@ export const peer = defineUnit({
   },
 })
 
+/**
+ * Patches some properties of the WireGuard peer.
+ */
 export const peerPatch = defineUnit({
-  type: "wireguard.peer-patch",
+  type: "wireguard.peer-patch.v1",
 
   args: {
     /**
      * The endpoints of the WireGuard peer.
      */
-    endpoints: Type.Default(Type.Array(Type.String()), []),
+    endpoints: z.string().array().default([]),
 
     /**
      * The mode to use for patching the endpoints.
@@ -325,14 +351,14 @@ export const peerPatch = defineUnit({
      * - `prepend`: prepend the new endpoints to the existing ones (default);
      * - `replace`: replace the existing endpoints with the new ones.
      */
-    endpointsPatchMode: Type.Default(arrayPatchModeSchema, "prepend"),
+    endpointsPatchMode: arrayPatchModeSchema.default("prepend"),
 
     /**
      * The allowed endpoints of the WireGuard peer.
      *
      * The non `hostname` endpoints will be added to the `allowedIps` of the peer.
      */
-    allowedEndpoints: Type.Default(Type.Array(Type.String()), []),
+    allowedEndpoints: z.string().array().default([]),
 
     /**
      * The mode to use for patching the allowed endpoints.
@@ -340,7 +366,7 @@ export const peerPatch = defineUnit({
      * - `prepend`: prepend the new endpoints to the existing ones (default);
      * - `replace`: replace the existing endpoints with the new ones.
      */
-    allowedEndpointsPatchMode: Type.Default(arrayPatchModeSchema, "prepend"),
+    allowedEndpointsPatchMode: arrayPatchModeSchema.default("prepend"),
 
     ...omit(sharedPeerArgs, ["endpoints", "allowedEndpoints"]),
   },
@@ -361,10 +387,9 @@ export const peerPatch = defineUnit({
   },
 
   meta: {
-    displayName: "WireGuard Peer Patch",
-    description: "Patches some properties of the WireGuard peer.",
-    primaryIcon: "simple-icons:wireguard",
-    primaryIconColor: "#88171a",
+    title: "WireGuard Peer Patch",
+    icon: "simple-icons:wireguard",
+    iconColor: "#88171a",
     secondaryIcon: "mdi:badge-account-horizontal",
     category: "VPN",
   },
@@ -375,8 +400,11 @@ export const peerPatch = defineUnit({
   },
 })
 
+/**
+ * The WireGuard identity with the public key.
+ */
 export const identity = defineUnit({
-  type: "wireguard.identity",
+  type: "wireguard.identity.v1",
 
   args: {
     ...sharedPeerArgs,
@@ -386,7 +414,7 @@ export const identity = defineUnit({
      *
      * Used by the implementation of the identity and to calculate the endpoint of the peer.
      */
-    listenPort: Type.Optional(Type.Number()),
+    listenPort: z.number().optional(),
 
     /**
      * The endpoint of the WireGuard peer.
@@ -395,7 +423,7 @@ export const identity = defineUnit({
      *
      * Will take priority over all calculated endpoints and `l4Endpoint` input.
      */
-    endpoints: Type.Default(Type.Array(Type.String()), []),
+    endpoints: z.string().array().default([]),
   },
 
   secrets: {
@@ -404,14 +432,14 @@ export const identity = defineUnit({
      *
      * If not provided, the key will be generated automatically.
      */
-    privateKey: Type.Optional(Type.String()),
+    privateKey: z.string().optional(),
 
     /**
      * The part of the pre-shared of the WireGuard identity.
      *
      * Will be generated automatically if not provided.
      */
-    presharedKeyPart: Type.Optional(Type.String()),
+    presharedKeyPart: z.string().optional(),
   },
 
   inputs: sharedPeerInputs,
@@ -422,9 +450,8 @@ export const identity = defineUnit({
   },
 
   meta: {
-    description: "The WireGuard identity with the public key.",
-    primaryIcon: "simple-icons:wireguard",
-    primaryIconColor: "#88171a",
+    icon: "simple-icons:wireguard",
+    iconColor: "#88171a",
     secondaryIcon: "mdi:account",
     category: "VPN",
   },
@@ -435,8 +462,11 @@ export const identity = defineUnit({
   },
 })
 
-export const node = defineUnit({
-  type: "wireguard.node",
+/**
+ * The WireGuard node deployed in the Kubernetes cluster.
+ */
+export const nodeK8s = defineUnit({
+  type: "wireguard.node.k8s.v1",
 
   args: {
     /**
@@ -444,12 +474,12 @@ export const node = defineUnit({
      *
      * By default, the name is `wg-${identity.name}`.
      */
-    appName: Type.Optional(Type.String()),
+    appName: z.string().optional(),
 
     /**
      * Whether to expose the WireGuard node to the outside world.
      */
-    external: Type.Default(Type.Boolean(), false),
+    external: z.boolean().default(false),
 
     /**
      * The policy to use for exposing the WireGuard node.
@@ -460,14 +490,14 @@ export const node = defineUnit({
      *
      * * By default, the `when-has-endpoint` policy is used.
      */
-    exposePolicy: Type.Default(nodeExposePolicySchema, "when-has-endpoint"),
+    exposePolicy: nodeExposePolicySchema.default("when-has-endpoint"),
 
     /**
      * The extra specification of the container which runs the WireGuard node.
      *
      * Will override any overlapping fields.
      */
-    containerSpec: Type.Optional(Type.Record(Type.String(), Type.Any())),
+    containerSpec: z.record(z.string(), z.unknown()).optional(),
 
     /**
      * List of CIDR blocks that should be blocked from forwarding through this WireGuard node.
@@ -477,7 +507,7 @@ export const node = defineUnit({
      *
      * Useful for peer isolation where you want to prevent cross-peer communication.
      */
-    forwardRestrictedIps: Type.Default(Type.Array(Type.String()), []),
+    forwardRestrictedIps: z.string().array().default([]),
   },
 
   inputs: {
@@ -490,7 +520,7 @@ export const node = defineUnit({
     },
 
     interface: {
-      entity: interfaceEntity,
+      entity: networkInterfaceEntity,
       required: false,
     },
 
@@ -503,10 +533,110 @@ export const node = defineUnit({
 
   outputs: {
     interface: {
-      entity: interfaceEntity,
+      entity: networkInterfaceEntity,
+      required: false,
+    },
+
+    peer: {
+      entity: peerEntity,
+      required: false,
+    },
+
+    endpoints: {
+      entity: l4EndpointEntity,
+      required: false,
+      multiple: true,
+    },
+  },
+
+  meta: {
+    title: "WireGuard Kubernetes Node",
+    icon: "simple-icons:wireguard",
+    iconColor: "#88171a",
+    secondaryIcon: "devicon:kubernetes",
+    category: "VPN",
+  },
+
+  source: {
+    package: "@highstate/wireguard",
+    path: "node.k8s",
+  },
+})
+
+/**
+ * The WireGuard node deployed on a server using wg-quick systemd service.
+ */
+export const node = defineUnit({
+  type: "wireguard.node.v1",
+
+  args: {
+    /**
+     * The name of the WireGuard interface.
+     *
+     * By default, the name is `wg-${identity.name}` (truncated to 15 characters).
+     */
+    interfaceName: z.string().optional(),
+
+    /**
+     * The name of the default interface for excluded routes.
+     *
+     * This is used to route excluded IPs through the default interface instead of the WireGuard tunnel.
+     */
+    defaultInterface: z.string().default("eth0"),
+
+    /**
+     * List of CIDR blocks that should be blocked from forwarding through this WireGuard node.
+     *
+     * This prevents other peers from reaching these destination CIDRs while still allowing
+     * the peers in those CIDRs to access the internet and other allowed endpoints.
+     *
+     * Useful for peer isolation where you want to prevent cross-peer communication.
+     */
+    forwardRestrictedIps: z.string().array().default([]),
+
+    /**
+     * Whether to enable IP masquerading (NAT) for outgoing traffic.
+     *
+     * By default, IP masquerading is enabled.
+     */
+    enableMasquerade: z.boolean().default(true),
+
+    /**
+     * Script to run before bringing up the interface.
+     */
+    preUpScript: z.string().optional().meta({ language: "shell" }),
+
+    /**
+     * Script to run after bringing up the interface.
+     */
+    postUpScript: z.string().optional().meta({ language: "shell" }),
+
+    /**
+     * Script to run before bringing down the interface.
+     */
+    preDownScript: z.string().optional().meta({ language: "shell" }),
+
+    /**
+     * Script to run after bringing down the interface.
+     */
+    postDownScript: z.string().optional().meta({ language: "shell" }),
+  },
+
+  inputs: {
+    identity: identityEntity,
+    server: {
+      entity: serverEntity,
+      required: true,
+    },
+
+    peers: {
+      entity: peerEntity,
+      multiple: true,
       required: false,
     },
+  },
 
+  outputs: {
     peer: {
       entity: peerEntity,
       required: false,
@@ -520,9 +650,9 @@ export const node = defineUnit({
   },
 
   meta: {
-    description: "The WireGuard node running on the Kubernetes.",
-    primaryIcon: "simple-icons:wireguard",
-    primaryIconColor: "#88171a",
+    title: "WireGuard Server Node",
+    icon: "simple-icons:wireguard",
+    iconColor: "#88171a",
     secondaryIcon: "mdi:server",
     category: "VPN",
   },
@@ -533,8 +663,11 @@ export const node = defineUnit({
   },
 })
 
+/**
+ * Just the WireGuard configuration for the identity and peers.
+ */
 export const config = defineUnit({
-  type: "wireguard.config",
+  type: "wireguard.config.v1",
 
   args: {
     /**
@@ -542,7 +675,7 @@ export const config = defineUnit({
      *
      * If not provided, the config will not respect `excludedIps`.
      */
-    defaultInterface: Type.Optional(Type.String()),
+    defaultInterface: z.string().optional(),
   },
 
   inputs: {
@@ -555,10 +688,9 @@ export const config = defineUnit({
   },
 
   meta: {
-    displayName: "WireGuard Config",
-    description: "Just the WireGuard configuration for the identity and peers.",
-    primaryIcon: "simple-icons:wireguard",
-    primaryIconColor: "#88171a",
+    title: "WireGuard Config",
+    icon: "simple-icons:wireguard",
+    iconColor: "#88171a",
     secondaryIcon: "mdi:settings",
     category: "VPN",
   },
@@ -569,8 +701,11 @@ export const config = defineUnit({
   },
 })
 
+/**
+ * The WireGuard configuration bundle for the identity and peers.
+ */
 export const configBundle = defineUnit({
-  type: "wireguard.config-bundle",
+  type: "wireguard.config-bundle.v1",
 
   inputs: {
     identity: identityEntity,
@@ -586,10 +721,9 @@ export const configBundle = defineUnit({
   },
 
   meta: {
-    displayName: "WireGuard Config Bundle",
-    description: "The WireGuard configuration bundle for the identity and peers.",
-    primaryIcon: "simple-icons:wireguard",
-    primaryIconColor: "#88171a",
+    title: "WireGuard Config Bundle",
+    icon: "simple-icons:wireguard",
+    iconColor: "#88171a",
     secondaryIcon: "mdi:folder-settings-variant",
     category: "VPN",
   },