@highstate/library 0.19.1 → 0.21.1

package/src/wireguard.ts

@@ -5,13 +5,15 @@ import {
   defineEntity,
   defineUnit,
   type EntityInput,
+  type EntityValue,
   genericNameSchema,
+  secretSchema,
   z,
 } from "@highstate/contract"
 import { pick } from "remeda"
 import { fileEntity } from "./common"
 import { serverEntity } from "./common/server"
-import { etcdEntity } from "./databases"
+import { etcd } from "./databases"
 import { clusterEntity, networkInterfaceEntity, workloadEntity } from "./k8s"
 import {
   addressEntity,
@@ -25,14 +27,37 @@ import { toPatchArgs } from "./utils"
 export const backendSchema = z.enum(["wireguard", "amneziawg"])
 
 export type Backend = z.infer<typeof backendSchema>
+export type AmneziaParameters = z.infer<typeof amneziaParametersSchema>
+
+export const amneziaParametersSchema = z.object({
+  i1: z.string().optional(),
+  i2: z.string().optional(),
+  i3: z.string().optional(),
+  i4: z.string().optional(),
+  i5: z.string().optional(),
+
+  s1: z.number().optional(),
+  s2: z.number().optional(),
+  s3: z.number().optional(),
+  s4: z.number().optional(),
+
+  jc: z.number().optional(),
+  jmin: z.number().optional(),
+  jmax: z.number().optional(),
+
+  h1: z.string().optional(),
+  h2: z.string().optional(),
+  h3: z.string().optional(),
+  h4: z.string().optional(),
+})
 
-const networkArgs = {
+export const networkArgs = {
   /**
    * The backend to use for the WireGuard network.
    *
    * Possible values are:
    * - `wireguard` - the default backend;
-   * - `amneziawg` - the censorship-resistant fork of WireGuard (NOT SUPPORTED YET).
+   * - `amneziawg` - the censorship-resistant fork of WireGuard.
    */
   backend: backendSchema.default("wireguard"),
 
@@ -51,8 +76,31 @@ const networkArgs = {
    * By default, IPv6 support is disabled.
    */
   ipv6: z.boolean().default(false),
+
+  /**
+   * The extra parameters for the amneziawg backend.
+   */
+  amnezia: amneziaParametersSchema.optional(),
 }
 
+const configSharedArgs = $args({
+  /**
+   * The filter to use when selecting endpoints for each peer.
+   *
+   * The first matching endpoint will be used.
+   *
+   * If not provided, all endpoints will be considered.
+   */
+  peerEndpointFilter: z.string().optional().meta({ language: "javascript" }),
+
+  /**
+   * Whether to include the `ListenPort` in the generated config.
+   *
+   * By default, is `false` because in most cases the config is used for peers which don't listen for incoming connections.
+   */
+  listen: z.boolean().default(false),
+})
+
 /**
  * The entity representing the WireGuard network configuration.
  *
@@ -62,47 +110,139 @@ export const networkEntity = defineEntity({
   type: "wireguard.network.v1",
 
   schema: z.object(networkArgs),
+
+  meta: {
+    color: "#88171a",
+    title: "WireGuard Network",
+    icon: "simple-icons:wireguard",
+    iconColor: "#88171a",
+    secondaryIcon: "mdi:local-area-network-connect",
+  },
 })
 
 export const nodeExposePolicySchema = z.enum(["always", "when-has-endpoint", "never"])
 
+export const feedDisplayInfoSchema = z.object({
+  /**
+   * The display title of the tunnel.
+   */
+  title: z.string(),
+
+  /**
+   * The display description of the tunnel.
+   */
+  description: z.string().optional(),
+
+  /**
+   * The display icon URL of the tunnel.
+   *
+   * Must only be `data:` URL with SVG image.
+   */
+  iconUrl: z.url().optional(),
+})
+
+export const feedMetadataSchema = z.object({
+  /**
+   * The ID of the tunnel in the feed.
+   */
+  id: z.string(),
+
+  /**
+   * The suggested name of the interface for the tunnel.
+   */
+  name: genericNameSchema,
+
+  /**
+   * Whether the tunnel should be enabled by the client.
+   */
+  enabled: z.boolean().default(false),
+
+  /**
+   * Whether the tunnel state must be forced by the client.
+   */
+  forced: z.boolean().default(false),
+
+  /**
+   * Whether the tunnel is exclusive and should not be enabled with other tunnels.
+   */
+  exclusive: z.boolean().default(false),
+
+  /**
+   * The display information of the tunnel.
+   */
+  displayInfo: feedDisplayInfoSchema,
+})
+
 export const peerEntity = defineEntity({
   type: "wireguard.peer.v1",
 
   includes: {
     /**
-     * The endpoints where the WireGuard peer can be reached.
+     * The network to which the WireGuard peer belongs.
+     *
+     * Holds shared configuration for all identities, peers, and nodes.
      */
-    endpoints: {
-      entity: l4EndpointEntity,
+    network: {
+      entity: networkEntity,
+      required: false,
+    },
+
+    /**
+     * The addresses of the WireGuard interface.
+     */
+    addresses: {
+      entity: addressEntity,
       multiple: true,
+      required: false,
     },
-  },
 
-  schema: z.object({
     /**
-     * The name of the WireGuard peer.
+     * The list of DNS servers to setup for the interface connected to the WireGuard peer.
      */
-    name: genericNameSchema,
+    dns: {
+      entity: addressEntity,
+      multiple: true,
+      required: false,
+    },
 
     /**
-     * The network to which the WireGuard peer belongs.
+     * The allowed subnets of the WireGuard peer.
      *
-     * Holds shared configuration for all identities, peers, and nodes.
+     * Will be used to configure the `AllowedIPs` of the peer.
      */
-    network: networkEntity.schema.optional(),
+    allowedSubnets: {
+      entity: subnetEntity,
+      multiple: true,
+      required: false,
+    },
 
     /**
-     * The addresses of the WireGuard interface.
+     * The endpoints where the WireGuard peer can be reached.
      */
-    addresses: addressEntity.schema.array(),
+    endpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+      required: false,
+    },
 
     /**
-     * The allowed subnets of the WireGuard peer.
+     * The peers which are relayed through this peer.
      *
-     * Will be used to configure the `AllowedIPs` of the peer.
+     * All their allowed IPs will be added to this peer's allowed IPs
+     * and will be used to setup routing for all other peers except the relayed ones.
      */
-    allowedSubnets: subnetEntity.schema.array(),
+    relayedPeers: {
+      entity: () => peerEntity,
+      multiple: true,
+      required: false,
+    },
+  },
+
+  schema: z.object({
+    /**
+     * The name of the WireGuard peer.
+     */
+    name: genericNameSchema,
 
     /**
      * The public key of the WireGuard peer.
@@ -116,19 +256,14 @@ export const peerEntity = defineEntity({
      *
      * Will be ignored if both peers have `presharedKeyPart` set.
      */
-    presharedKey: z.string().optional(),
+    presharedKey: secretSchema(z.string()).optional(),
 
     /**
      * The pre-shared key part of the WireGuard peer.
      *
      * If both peers have `presharedKeyPart` set, their `presharedKey` will be calculated as sha256 of the two parts.
      */
-    presharedKeyPart: z.string().optional(),
-
-    /**
-     * The list of DNS servers to setup for the interface connected to the WireGuard peer.
-     */
-    dns: addressEntity.schema.array(),
+    presharedKeyPart: secretSchema(z.string()).optional(),
 
     /**
      * The port where the WireGuard peer is listening.
@@ -147,18 +282,18 @@ export const peerEntity = defineEntity({
     persistentKeepalive: z.number().int().nonnegative().default(0),
 
     /**
-     * The peers which are relayed through this peer.
+     * The wg-feed metadata of the WireGuard peer.
      *
-     * All their allowed IPs will be added to this peer's allowed IPs
-     * and will be used to setup routing for all other peers except the relayed ones.
+     * Will be used in the config referencing this peer (not the peer itself).
      */
-    get relayedPeers() {
-      return peerEntity.schema.array().optional()
-    },
+    feedMetadata: feedMetadataSchema.optional(),
   }),
 
   meta: {
     color: "#673AB7",
+    icon: "simple-icons:wireguard",
+    secondaryIcon: "mdi:badge-account-horizontal",
+    iconColor: "#88171a",
   },
 })
 
@@ -176,50 +311,17 @@ export const identityEntity = defineEntity({
     /**
      * The private key of the WireGuard identity.
      */
-    privateKey: z.string(),
+    privateKey: secretSchema(z.string()),
   }),
 
   meta: {
     color: "#F44336",
+    icon: "simple-icons:wireguard",
+    secondaryIcon: "mdi:account",
+    iconColor: "#88171a",
   },
 })
 
-export const feedDisplayInfoSchema = z.object({
-  /**
-   * The display title of the tunnel.
-   */
-  title: z.string(),
-
-  /**
-   * The display description of the tunnel.
-   */
-  description: z.string().optional(),
-
-  /**
-   * The display icon URL of the tunnel.
-   *
-   * Must only be `data:` URL with SVG image.
-   */
-  iconUrl: z.url().optional(),
-})
-
-export const feedMetadataSchema = z.object({
-  /**
-   * The ID of the tunnel in the feed.
-   */
-  id: z.string(),
-
-  /**
-   * The suggested name of the interface for the tunnel.
-   */
-  name: genericNameSchema,
-
-  /**
-   * The display information of the tunnel.
-   */
-  displayInfo: feedDisplayInfoSchema,
-})
-
 export const configEntity = defineEntity({
   type: "wireguard.config.v1",
 
@@ -238,19 +340,30 @@ export const configEntity = defineEntity({
      */
     feedMetadata: feedMetadataSchema.optional(),
   }),
+
+  meta: {
+    color: "#455A64",
+    title: "WireGuard Config",
+    icon: "simple-icons:wireguard",
+    iconColor: "#88171a",
+    secondaryIcon: "mdi:settings",
+  },
 })
 
-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 Network = EntityValue<typeof networkEntity>
+export type Identity = EntityValue<typeof identityEntity>
+export type Peer = EntityValue<typeof peerEntity>
 export type NodeExposePolicy = z.infer<typeof nodeExposePolicySchema>
-export type Config = z.infer<typeof configEntity.schema>
+export type Config = EntityValue<typeof configEntity>
 
 export type NetworkInput = EntityInput<typeof networkEntity>
 export type IdentityInput = EntityInput<typeof identityEntity>
 export type PeerInput = EntityInput<typeof peerEntity>
 export type ConfigInput = EntityInput<typeof configEntity>
 
+export type FeedDisplayInfo = z.infer<typeof feedDisplayInfoSchema>
+export type FeedMetadata = z.infer<typeof feedMetadataSchema>
+
 /**
  * Holds the shared configuration for WireGuard identities, peers, and nodes.
  */
@@ -276,6 +389,35 @@ export const network = defineUnit({
   },
 })
 
+const sharedFeedArgs = $args({
+  /**
+   * The metadata to include in the wg-feed for this config.
+   */
+  feedMetadata: z
+    .discriminatedUnion("provided", [
+      z.object({
+        /**
+         * Whether this config is enabled for upload to wg-feed.
+         *
+         * You must fill the metadata fields.
+         */
+        provided: z.literal("yes"),
+
+        ...pick(feedMetadataSchema.shape, ["id", "name", "enabled", "forced", "exclusive"]),
+
+        // Highstate does not support nested objects in UI
+        ...feedDisplayInfoSchema.shape,
+      }),
+      z.object({
+        /**
+         * Whether this config is enabled for upload to wg-feed.
+         */
+        provided: z.literal("no"),
+      }),
+    ])
+    .prefault({ provided: "no" }),
+})
+
 const sharedPeerArgs = $args({
   /**
    * The name of the WireGuard peer.
@@ -363,6 +505,8 @@ const sharedPeerArgs = $args({
    * If set to 0, keepalive is disabled.
    */
   persistentKeepalive: z.number().int().nonnegative().default(0),
+
+  ...sharedFeedArgs,
 })
 
 const sharedPeerInputs = $inputs({
@@ -589,6 +733,14 @@ export const nodeK8s = defineUnit({
      * By default, is false.
      */
     allowClusterPods: z.boolean().default(false),
+
+    /**
+     * Whether to drop all traffic from the interface using ip rule with priority 100.
+     *
+     * This is useful for preventing the traffic leaks before upstream node is attached via `downstreamInterface` input.
+     * They will add their own ip rule with <100 priority which allows traffic from the interface.
+     */
+    lockdownUpstream: z.boolean().default(false),
   },
 
   inputs: {
@@ -600,7 +752,12 @@ export const nodeK8s = defineUnit({
       required: false,
     },
 
-    interface: {
+    downstreamInterface: {
+      entity: networkInterfaceEntity,
+      required: false,
+    },
+
+    fallbackInterface: {
       entity: networkInterfaceEntity,
       required: false,
     },
@@ -640,6 +797,128 @@ export const nodeK8s = defineUnit({
   },
 })
 
+/**
+ * The wg-feed daemon deployed in the Kubernetes cluster.
+ *
+ * It runs `wg-feed-daemon` which continuously reconciles local WireGuard tunnels
+ * from one or more wg-feed Setup URLs.
+ */
+export const nodeFeedK8s = defineUnit({
+  type: "wireguard.node.feed.k8s.v1",
+
+  args: {
+    /**
+     * The name of the namespace/deployment/statefulset where the daemon will be deployed.
+     *
+     * By default, the name is `wg-${identity.name}`.
+     */
+    appName: z.string().optional(),
+
+    /**
+     * Whether to expose the WireGuard node to the outside world.
+     */
+    external: z.boolean().default(false),
+
+    /**
+     * Whether to create a Service and allow ingress.
+     */
+    expose: z.boolean().default(false),
+
+    /**
+     * The UDP port that will be exposed by the Service.
+     *
+     * This is required for consumers that need to know the port ahead of time.
+     */
+    listenPort: z.number().default(51820),
+
+    /**
+     * The name of the WireGuard interface to export as `interface` output.
+     *
+     * Note: wg-feed may manage multiple tunnels.
+     * This output is a convenience handle for downstream units.
+     */
+    interfaceName: z.string().default("wg0"),
+
+    /**
+     * 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.
+     */
+    forwardRestrictedSubnets: z.string().array().default([]),
+
+    /**
+     * Whether to drop all traffic from the interface using ip rule with priority 100.
+     *
+     * This is useful for preventing the traffic leaks before upstream node is attached via `downstreamInterface` input.
+     * They will add their own ip rule with <100 priority which allows traffic from the interface.
+     */
+    lockdownUpstream: z.boolean().default(false),
+
+    /**
+     * The extra specification of the container which runs the wg-feed daemon.
+     *
+     * Will override any overlapping fields.
+     */
+    containerSpec: z.record(z.string(), z.unknown()).optional(),
+  },
+
+  inputs: {
+    k8sCluster: clusterEntity,
+    endpoints: {
+      entity: l7EndpointEntity,
+      multiple: true,
+      required: false,
+    },
+
+    peer: {
+      entity: peerEntity,
+      required: false,
+    },
+
+    workload: {
+      entity: workloadEntity,
+      required: false,
+    },
+
+    interface: {
+      entity: networkInterfaceEntity,
+      required: false,
+    },
+  },
+
+  outputs: {
+    workload: {
+      entity: workloadEntity,
+    },
+
+    interface: {
+      entity: networkInterfaceEntity,
+    },
+
+    peer: {
+      entity: peerEntity,
+      required: false,
+    },
+  },
+
+  meta: {
+    title: "WireGuard Feed Kubernetes Node",
+    description: "The wg-feed daemon deployed in the Kubernetes cluster.",
+    icon: "simple-icons:wireguard",
+    iconColor: "#88171a",
+    secondaryIcon: "devicon:kubernetes",
+    category: "VPN",
+  },
+
+  source: {
+    package: "@highstate/wireguard",
+    path: "node.feed.k8s",
+  },
+})
+
 /**
  * The WireGuard node deployed on a server using wg-quick systemd service.
  */
@@ -671,6 +950,8 @@ export const node = defineUnit({
      */
     enableMasquerade: z.boolean().default(true),
 
+    ...configSharedArgs,
+
     /**
      * Script to run before bringing up the interface.
      */
@@ -711,12 +992,6 @@ export const node = defineUnit({
       entity: peerEntity,
       required: false,
     },
-
-    endpoints: {
-      entity: l4EndpointEntity,
-      required: false,
-      multiple: true,
-    },
   },
 
   meta: {
@@ -733,17 +1008,6 @@ export const node = defineUnit({
   },
 })
 
-const sharedArgs = $args({
-  /**
-   * The filter to use when selecting endpoints for each peer.
-   *
-   * The first matching endpoint will be used.
-   *
-   * If not provided, all endpoints will be considered.
-   */
-  peerEndpointFilter: z.string().optional().meta({ language: "javascript" }),
-})
-
 /**
  * Just the WireGuard configuration for the identity and peers.
  */
@@ -751,34 +1015,8 @@ export const config = defineUnit({
   type: "wireguard.config.v1",
 
   args: {
-    ...sharedArgs,
-
-    /**
-     * The metadata to include in the wg-feed for this config.
-     */
-    feedMetadata: z
-      .discriminatedUnion("enabled", [
-        z.object({
-          /**
-           * Whether this config is enabled for upload to wg-feed.
-           *
-           * You must fill the metadata fields.
-           */
-          enabled: z.literal("true"),
-
-          ...pick(feedMetadataSchema.shape, ["id", "name"]),
-
-          // Highstate does not support nested objects in UI
-          ...feedDisplayInfoSchema.shape,
-        }),
-        z.object({
-          /**
-           * Whether this config is enabled for upload to wg-feed.
-           */
-          enabled: z.literal("false"),
-        }),
-      ])
-      .prefault({ enabled: "false" }),
+    ...configSharedArgs,
+    ...sharedFeedArgs,
   },
 
   inputs: {
@@ -788,6 +1026,10 @@ export const config = defineUnit({
       multiple: true,
       required: false,
     },
+    network: {
+      entity: networkEntity,
+      required: false,
+    },
   },
 
   outputs: {
@@ -815,7 +1057,7 @@ export const configBundle = defineUnit({
   type: "wireguard.config-bundle.v1",
 
   args: {
-    ...sharedArgs,
+    ...configSharedArgs,
   },
 
   inputs: {
@@ -909,7 +1151,7 @@ export const feed = defineUnit({
   },
 
   inputs: {
-    etcd: etcdEntity,
+    etcd: etcd.connectionEntity,
     serverEndpoints: {
       entity: l4EndpointEntity,
       required: false,

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Exeteres
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.