@highstate/library 0.9.3 → 0.9.5

package/src/wireguard.ts

@@ -1,53 +1,23 @@
-import { defineEntity, defineUnit, Type, type Static } from "@highstate/contract"
-import {
-  clusterEntity,
-  deploymentEntity,
-  interfaceEntity,
-  serviceEntity,
-  serviceTypeSchema,
-  statefulSetEntity,
-} from "./k8s"
-import { providerEntity } from "./dns"
-import { l4EndpointEntity } from "./common"
+import { defineEntity, defineUnit, Type, type Static, type TObject } from "@highstate/contract"
+import { omit } from "remeda"
+import { clusterEntity, interfaceEntity, exposableWorkloadEntity } from "./k8s"
+import { l3EndpointEntity, l4EndpointEntity } from "./network"
+import { arrayPatchModeSchema } from "./utils"
 
 export const backendSchema = Type.StringEnum(["wireguard", "amneziawg"])
-export const presharedKeyModeSchema = Type.StringEnum(["none", "global", "secure"])
 
 export type Backend = Static<typeof backendSchema>
-export type PresharedKeyMode = Static<typeof presharedKeyModeSchema>
 
 export const networkEntity = defineEntity({
   type: "wireguard.network",
 
   schema: Type.Object({
-    backend: Type.Optional(backendSchema),
-    presharedKeyMode: presharedKeyModeSchema,
-    globalPresharedKey: Type.Optional(Type.String()),
-    ipv6: Type.Optional(Type.Boolean()),
+    backend: backendSchema,
+    ipv6: Type.Boolean(),
   }),
 })
 
-export const identityEntity = defineEntity({
-  type: "wireguard.identity",
-
-  schema: Type.Object({
-    name: Type.String(),
-    network: Type.Optional(networkEntity.schema),
-    address: Type.Optional(Type.String()),
-    privateKey: Type.String(),
-    presharedKeyPart: Type.Optional(Type.String()),
-    k8sServices: Type.Array(serviceEntity.schema),
-    exitNode: Type.Boolean(),
-    listenPort: Type.Optional(Type.Number()),
-    externalIp: Type.Optional(Type.String()),
-    endpoint: Type.Optional(Type.String()),
-    fqdn: Type.Optional(Type.String()),
-  }),
-
-  meta: {
-    color: "#F44336",
-  },
-})
+export const nodeExposePolicySchema = Type.StringEnum(["always", "when-has-endpoint", "never"])
 
 export const peerEntity = defineEntity({
   type: "wireguard.peer",
@@ -58,10 +28,28 @@ export const peerEntity = defineEntity({
     publicKey: Type.String(),
     address: Type.Optional(Type.String()),
     allowedIps: Type.Array(Type.String()),
-    endpoint: Type.Optional(Type.String()),
+    endpoints: Type.Array(l4EndpointEntity.schema),
+    allowedEndpoints: Type.Array(Type.Union([l3EndpointEntity.schema, l4EndpointEntity.schema])),
+
+    /**
+     * The pre-shared key of the WireGuard peer.
+     *
+     * If one of two peers has `presharedKey` set, the other peer must have `presharedKey` set too and they must be equal.
+     *
+     * Will be ignored if both peers have `presharedKeyPart` set.
+     */
+    presharedKey: Type.Optional(Type.String()),
+
+    /**
+     * 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()),
-    excludedIps: Type.Optional(Type.Array(Type.String())),
-    dns: Type.Optional(Type.Array(Type.String())),
+
+    excludedIps: Type.Array(Type.String()),
+    dns: Type.Array(Type.String()),
+    listenPort: Type.Optional(Type.Number()),
   }),
 
   meta: {
@@ -69,20 +57,23 @@ export const peerEntity = defineEntity({
   },
 })
 
-export const k8sNodeEntity = defineEntity({
-  type: "wireguard.node",
+export const identityEntity = defineEntity({
+  type: "wireguard.identity",
 
   schema: Type.Object({
-    network: Type.String(),
-    address: Type.String(),
-    endpoint: Type.Optional(Type.String()),
-    peers: Type.Array(Type.String()),
+    peer: peerEntity.schema,
+    privateKey: Type.String(),
   }),
+
+  meta: {
+    color: "#F44336",
+  },
 })
 
 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>
 
 /**
  * The network hols the shared configuration for the WireGuard identities, peers and nodes.
@@ -104,23 +95,6 @@ export const network = defineUnit({
      */
     backend: Type.Default(backendSchema, "wireguard"),
 
-    /**
-     * The option which defines how to handle pre-shared keys between peers.
-     *
-     * 1. `none` - No pre-shared keys will be used.
-     * 2. `global` - A single pre-shared key will be used for all peer pairs in the network.
-     * 3. `secure` - Each peer pair will have its own pre-shared key.
-     * In this case, each identity generates `presharedKeyPart` and the actual pre-shared key
-     * for each peer pair will be computed as `xor(peer1.presharedKeyPart, peer2.presharedKeyPart)`.
-     *
-     * If the whole network is managed by the HighState, the `secure` mode is recommended.
-     *
-     * By default, the `none` mode is used.
-     *
-     * @schema
-     */
-    presharedKeyMode: Type.Optional(presharedKeyModeSchema),
-
     /**
      * The option to enable IPv6 support in the network.
      *
@@ -128,19 +102,7 @@ export const network = defineUnit({
      *
      * @schema
      */
-    ipv6: Type.Optional(Type.Boolean()),
-  },
-
-  secrets: {
-    /**
-     * The global pre-shared key to use for all peer pairs in the network.
-     *
-     * Will be used only if `presharedKeyMode` is set to `global`.
-     * Will be generated automatically if not provided.
-     *
-     * @schema
-     */
-    globalPresharedKey: Type.Optional(Type.String()),
+    ipv6: Type.Default(Type.Boolean(), false),
   },
 
   outputs: {
@@ -152,6 +114,7 @@ export const network = defineUnit({
     primaryIcon: "simple-icons:wireguard",
     primaryIconColor: "#88171a",
     secondaryIcon: "mdi:local-area-network-connect",
+    category: "VPN",
   },
 
   source: {
@@ -179,13 +142,6 @@ const sharedPeerArgs = {
    */
   address: Type.Optional(Type.String()),
 
-  /**
-   * The list of allowed IPs for the peer.
-   *
-   * @schema
-   */
-  allowedIps: Type.Optional(Type.Array(Type.String())),
-
   /**
    * The convenience option to set `allowedIps` to `0.0.0.0/0, ::/0`.
    *
@@ -193,7 +149,7 @@ const sharedPeerArgs = {
    *
    * @schema
    */
-  exitNode: Type.Optional(Type.Boolean()),
+  exitNode: Type.Default(Type.Boolean(), false),
 
   /**
    * The list of IP ranges to exclude from the tunnel.
@@ -206,7 +162,7 @@ const sharedPeerArgs = {
    *
    * @schema
    */
-  excludedIps: Type.Optional(Type.Array(Type.String())),
+  excludedIps: Type.Default(Type.Array(Type.String()), []),
 
   /**
    * The convenience option to exclude private IPs from the tunnel.
@@ -226,14 +182,23 @@ const sharedPeerArgs = {
    *
    * @schema
    */
-  excludePrivateIps: Type.Optional(Type.Boolean()),
+  excludePrivateIps: Type.Default(Type.Boolean(), false),
 
   /**
-   * The endpoint of the WireGuard peer.
+   * The endpoints of the WireGuard peer.
    *
    * @schema
    */
-  endpoint: Type.Optional(Type.String()),
+  endpoints: Type.Default(Type.Array(Type.String()), []),
+
+  /**
+   * The allowed endpoints of the WireGuard peer.
+   *
+   * The non `hostname` endpoints will be added to the `allowedIps` of the peer.
+   *
+   * @schema
+   */
+  allowedEndpoints: Type.Default(Type.Array(Type.String()), []),
 
   /**
    * The DNS servers that should be used by the interface connected to the WireGuard peer.
@@ -242,7 +207,7 @@ const sharedPeerArgs = {
    *
    * @schema
    */
-  dns: Type.Optional(Type.Array(Type.String())),
+  dns: Type.Default(Type.Array(Type.String()), []),
 
   /**
    * The convenience option to include the DNS servers to the allowed IPs.
@@ -251,28 +216,97 @@ const sharedPeerArgs = {
    *
    * @schema
    */
-  includeDns: Type.Optional(Type.Boolean({ default: true })),
-}
+  includeDns: Type.Default(Type.Boolean(), true),
 
-const sharedInterfaceArgs = {
   /**
    * The port to listen on.
    *
-   * Will override the `listenPort` of the identity if provided.
-   *
    * @schema
    */
   listenPort: Type.Optional(Type.Number()),
+}
 
+const sharedPeerInputs = {
   /**
-   * The DNS servers that should be used by the interface connected to the WireGuard node.
+   * The network to use for the WireGuard identity.
    *
-   * Will be merged with the DNS servers of the peers.
+   * If not provided, the identity will use default network configuration.
    *
    * @schema
    */
-  dns: Type.Optional(Type.Array(Type.String())),
-}
+  network: {
+    entity: networkEntity,
+    required: false,
+  },
+
+  /**
+   * The L3 endpoints of the identity.
+   *
+   * Will produce L4 endpoints for each of the provided L3 endpoints.
+   *
+   * @schema
+   */
+  l3Endpoints: {
+    entity: l3EndpointEntity,
+    multiple: true,
+    required: false,
+  },
+
+  /**
+   * The L4 endpoints of the identity.
+   *
+   * Will take priority over all calculated endpoints if provided.
+   *
+   * @schema
+   */
+  l4Endpoints: {
+    entity: l4EndpointEntity,
+    required: false,
+    multiple: true,
+  },
+
+  /**
+   * The L3 endpoints to add to the allowed IPs of the identity.
+   *
+   * `hostname` endpoints will be ignored.
+   *
+   * If the endpoint contains k8s service metadata of the cluster where the identity node is deployed,
+   * the corresponding network policy will be created.
+   *
+   * @schema
+   */
+  allowedL3Endpoints: {
+    entity: l3EndpointEntity,
+    multiple: true,
+    required: false,
+  },
+
+  /**
+   * The L4 endpoints to add to the allowed IPs of the identity.
+   *
+   * If the endpoint contains k8s service metadata of the cluster where the identity node is deployed,
+   * the corresponding network policy will be created.
+   *
+   * @schema
+   */
+  allowedL4Endpoints: {
+    entity: l4EndpointEntity,
+    multiple: true,
+    required: false,
+  },
+} as const
+
+const sharedPeerOutputs = {
+  peer: peerEntity,
+
+  endpoints: {
+    entity: l4EndpointEntity,
+    required: false,
+    multiple: true,
+  },
+} as const
+
+export type SharedPeerArgs = Static<TObject<typeof sharedPeerArgs>>
 
 export const peer = defineUnit({
   type: "wireguard.peer",
@@ -285,59 +319,101 @@ export const peer = defineUnit({
      *
      * @schema
      */
-    publicKey: Type.Optional(Type.String()),
+    publicKey: Type.String(),
   },
 
-  inputs: {
+  secrets: {
     /**
-     * The network to use for the WireGuard peer.
-     *
-     * If not provided, the peer will use default network configuration.
+     * The pre-shared key which should be used for the peer.
      *
      * @schema
      */
-    network: {
-      entity: networkEntity,
-      required: false,
-    },
+    presharedKey: Type.Optional(Type.String()),
+  },
 
+  inputs: sharedPeerInputs,
+  outputs: sharedPeerOutputs,
+
+  meta: {
+    description: "The WireGuard peer with the public key.",
+    primaryIcon: "simple-icons:wireguard",
+    primaryIconColor: "#88171a",
+    secondaryIcon: "mdi:badge-account-horizontal",
+    category: "VPN",
+  },
+
+  source: {
+    package: "@highstate/wireguard",
+    path: "peer",
+  },
+})
+
+export const peerPatch = defineUnit({
+  type: "wireguard.peer-patch",
+
+  args: {
     /**
-     * The existing WireGuard peer to extend.
+     * The endpoints of the WireGuard peer.
      *
      * @schema
      */
-    peer: {
-      entity: peerEntity,
-      required: false,
-    },
+    endpoints: Type.Default(Type.Array(Type.String()), []),
 
     /**
-     * The L4 endpoint of the peer.
+     * The mode to use for patching the endpoints.
      *
-     * Will take priority over all calculated endpoints if provided.
+     * - `prepend`: prepend the new endpoints to the existing ones (default);
+     * - `replace`: replace the existing endpoints with the new ones.
+     */
+    endpointsPatchMode: Type.Default(arrayPatchModeSchema, "prepend"),
+
+    /**
+     * The allowed endpoints of the WireGuard peer.
+     *
+     * The non `hostname` endpoints will be added to the `allowedIps` of the peer.
      *
      * @schema
      */
-    l4Endpoint: {
-      entity: l4EndpointEntity,
-      required: false,
-    },
+    allowedEndpoints: Type.Default(Type.Array(Type.String()), []),
+
+    /**
+     * The mode to use for patching the allowed endpoints.
+     *
+     * - `prepend`: prepend the new endpoints to the existing ones (default);
+     * - `replace`: replace the existing endpoints with the new ones.
+     */
+    allowedEndpointsPatchMode: Type.Default(arrayPatchModeSchema, "prepend"),
+
+    ...omit(sharedPeerArgs, ["endpoints", "allowedEndpoints"]),
+  },
+
+  inputs: {
+    peer: peerEntity,
+    ...sharedPeerInputs,
   },
 
   outputs: {
     peer: peerEntity,
+
+    endpoints: {
+      entity: l4EndpointEntity,
+      required: false,
+      multiple: true,
+    },
   },
 
   meta: {
-    description: "The WireGuard peer with the public key.",
+    displayName: "WireGuard Peer Patch",
+    description: "Patches some properties of the WireGuard peer.",
     primaryIcon: "simple-icons:wireguard",
     primaryIconColor: "#88171a",
     secondaryIcon: "mdi:badge-account-horizontal",
+    category: "VPN",
   },
 
   source: {
     package: "@highstate/wireguard",
-    path: "peer",
+    path: "peer-patch",
   },
 })
 
@@ -356,47 +432,16 @@ export const identity = defineUnit({
      */
     listenPort: Type.Optional(Type.Number()),
 
-    /**
-     * The external IP address of the WireGuard identity.
-     *
-     * Used by the implementation of the identity and to calculate the endpoint of the peer.
-     *
-     * @schema
-     */
-    externalIp: Type.Optional(Type.String()),
-
     /**
      * The endpoint of the WireGuard peer.
      *
-     * By default, the endpoint is calculated as `externalIp:listenPort`.
-     *
      * If overridden, does not affect node which implements the identity, but is used in the peer configuration of other nodes.
      *
      * Will take priority over all calculated endpoints and `l4Endpoint` input.
      *
      * @schema
      */
-    endpoint: Type.Optional(Type.String()),
-
-    /**
-     * The FQDN of the WireGuard identity.
-     * Will be used as endpoint for the peer.
-     *
-     * If `dnsProvider` is provided, external IP is available and `registerFqdn` is set to `true`, and FQDN is provided explicitly (not obtained from the k8s cluster),
-     * the FQDN will be registered with the DNS provider.
-     *
-     * @schema
-     */
-    fqdn: Type.Optional(Type.String()),
-
-    /**
-     * Whether to register the FQDN of the identity with the matching DNS providers.
-     *
-     * By default, `true`.
-     *
-     * @schema
-     */
-    registerFqdn: Type.Default(Type.Boolean(), true),
+    endpoints: Type.Default(Type.Array(Type.String()), []),
   },
 
   secrets: {
@@ -419,76 +464,11 @@ export const identity = defineUnit({
     presharedKeyPart: Type.Optional(Type.String()),
   },
 
-  inputs: {
-    /**
-     * The network to use for the WireGuard identity.
-     *
-     * If not provided, the identity will use default network configuration.
-     *
-     * @schema
-     */
-    network: {
-      entity: networkEntity,
-      required: false,
-    },
-
-    /**
-     * The list of Kubernetes services to expose the WireGuard identity.
-     *
-     * Their IP addresses will be added to the `allowedIps` of the identity and passed to the node to set up network policies.
-     *
-     * @schema
-     */
-    k8sServices: {
-      entity: serviceEntity,
-      multiple: true,
-      required: false,
-    },
-
-    /**
-     * The Kubernetes cluster associated with the identity.
-     *
-     * If provided, will be used to obtain the external IP or FQDN of the identity.
-     *
-     * @schema
-     */
-    k8sCluster: {
-      entity: clusterEntity,
-      required: false,
-    },
-
-    /**
-     * The L4 endpoint of the identity.
-     *
-     * Will take priority over all calculated endpoints if provided.
-     *
-     * @schema
-     */
-    l4Endpoint: {
-      entity: l4EndpointEntity,
-      required: false,
-    },
-
-    /**
-     * The DNS providers to register the FQDN of the identity with.
-     *
-     * @schema
-     */
-    dnsProviders: {
-      entity: providerEntity,
-      required: false,
-      multiple: true,
-    },
-  },
+  inputs: sharedPeerInputs,
 
   outputs: {
     identity: identityEntity,
-    peer: peerEntity,
-
-    l4Endpoint: {
-      entity: l4EndpointEntity,
-      required: false,
-    },
+    ...sharedPeerOutputs,
   },
 
   meta: {
@@ -496,6 +476,7 @@ export const identity = defineUnit({
     primaryIcon: "simple-icons:wireguard",
     primaryIconColor: "#88171a",
     secondaryIcon: "mdi:account",
+    category: "VPN",
   },
 
   source: {
@@ -508,19 +489,32 @@ export const node = defineUnit({
   type: "wireguard.node",
 
   args: {
+    /**
+     * The name of the namespace/deployment/statefulset where the WireGuard node will be deployed.
+     *
+     * By default, the name is `wg-${identity.name}`.
+     *
+     * @schema
+     */
     appName: Type.Optional(Type.String()),
-    serviceType: Type.Optional(serviceTypeSchema),
 
-    ...sharedInterfaceArgs,
+    /**
+     * Whether to expose the WireGuard node to the outside world.
+     *
+     * @schema
+     */
+    external: Type.Default(Type.Boolean(), false),
 
     /**
-     * The external IP address of the WireGuard node.
+     * The policy to use for exposing the WireGuard node.
      *
-     * Will override the `externalIp` of the identity if provided.
+     * - `always` - The node will be exposed and the service will be created.
+     * - `when-has-endpoint` - The node will be exposed only if the provided idenity has at least one endpoint.
+     * - `never` - The node will not be exposed and the service will not be created.
      *
-     * @schema
+     * * By default, the `when-has-endpoint` policy is used.
      */
-    externalIp: Type.Optional(Type.String()),
+    exposePolicy: Type.Default(nodeExposePolicySchema, "when-has-endpoint"),
 
     /**
      * The extra specification of the container which runs the WireGuard node.
@@ -536,13 +530,8 @@ export const node = defineUnit({
     identity: identityEntity,
     k8sCluster: clusterEntity,
 
-    deployment: {
-      entity: deploymentEntity,
-      required: false,
-    },
-
-    statefulSet: {
-      entity: statefulSetEntity,
+    workload: {
+      entity: exposableWorkloadEntity,
       required: false,
     },
 
@@ -559,19 +548,20 @@ export const node = defineUnit({
   },
 
   outputs: {
-    deployment: {
-      entity: deploymentEntity,
+    interface: {
+      entity: interfaceEntity,
       required: false,
     },
 
-    interface: {
-      entity: interfaceEntity,
+    peer: {
+      entity: peerEntity,
       required: false,
     },
 
-    service: {
-      entity: serviceEntity,
+    endpoints: {
+      entity: l4EndpointEntity,
       required: false,
+      multiple: true,
     },
   },
 
@@ -580,6 +570,7 @@ export const node = defineUnit({
     primaryIcon: "simple-icons:wireguard",
     primaryIconColor: "#88171a",
     secondaryIcon: "mdi:server",
+    category: "VPN",
   },
 
   source: {
@@ -592,8 +583,6 @@ export const config = defineUnit({
   type: "wireguard.config",
 
   args: {
-    ...sharedInterfaceArgs,
-
     /**
      * The name of the "default" interface where non-tunneled traffic should go.
      *
@@ -619,6 +608,7 @@ export const config = defineUnit({
     primaryIcon: "simple-icons:wireguard",
     primaryIconColor: "#88171a",
     secondaryIcon: "mdi:settings",
+    category: "VPN",
   },
 
   source: {
@@ -649,6 +639,7 @@ export const configBundle = defineUnit({
     primaryIcon: "simple-icons:wireguard",
     primaryIconColor: "#88171a",
     secondaryIcon: "mdi:folder-settings-variant",
+    category: "VPN",
   },
 
   source: {