@highstate/library 0.8.0 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highstate/library",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "type": "module",
   "files": [
     "dist",
@@ -19,12 +19,12 @@
     "build": "highstate build --library"
   },
   "dependencies": {
-    "@highstate/contract": "^0.8.0",
+    "@highstate/contract": "^0.9.1",
     "@sinclair/typebox": "^0.34.11",
     "remeda": "^2.21.0"
   },
   "devDependencies": {
-    "@highstate/cli": "^0.8.0"
+    "@highstate/cli": "^0.9.1"
   },
-  "gitHead": "8590eea089a016c9b4b797299fc94ddc9afe10ba"
+  "gitHead": "2f9fdd9542fbdd11d4337fb59ac4f5728535fa0c"
 }

package/src/common.ts

@@ -15,16 +15,30 @@ export const serverEntity = defineEntity({
   },
 })
 
-export const endpointEntity = defineEntity({
-  type: "common.endpoint",
+export const l3EndpointEntity = defineEntity({
+  type: "common.l3-endpoint",
 
   schema: Type.Object({
     endpoint: Type.String(),
   }),
 
   meta: {
-    color: "#FFC107",
-    description: "The L3-L4 endpoint for some network service.",
+    color: "#1B5E20",
+    description: "The L3 endpoint for some service. May be a domain name or an IP address.",
+  },
+})
+
+export const l4EndpointEntity = defineEntity({
+  type: "common.l4-endpoint",
+
+  schema: Type.Object({
+    endpoint: Type.String(),
+    port: Type.Number(),
+  }),
+
+  meta: {
+    color: "#F57F17",
+    description: "The L4 endpoint for some service. Extends an L3 endpoint with a port.",
   },
 })
 
@@ -145,7 +159,8 @@ export const fileEntity = defineEntity({
 })
 
 export type Server = Static<typeof serverEntity.schema>
-export type Endpoint = Static<typeof endpointEntity.schema>
+export type L3Endpoint = Static<typeof l3EndpointEntity.schema>
+export type L4Endpoint = Static<typeof l4EndpointEntity.schema>
 
 export type File = Static<typeof fileEntity.schema>
 export type FileMeta = Static<typeof fileMetaEntity.schema>

package/src/index.ts

@@ -7,10 +7,10 @@ export * as wireguard from "./wireguard"
 export * as apps from "./apps"
 export * as cloudflare from "./cloudflare"
 export * as k3s from "./k3s"
-// export * as xtWgobfs from "./xt-wgobfs"
 export * as restic from "./restic"
 export * as mullvad from "./mullvad"
 export * as dns from "./dns"
 export * as timeweb from "./timeweb"
 export * as nixos from "./nixos"
 export * as sops from "./sops"
+export * as obfuscators from "./obfuscators"

package/src/k8s.ts

@@ -1,6 +1,18 @@
 import { defineEntity, defineUnit, Type, type Static } from "@highstate/contract"
+import { Literal } from "@sinclair/typebox"
 import { providerEntity } from "./dns"
 
+export const tunDevicePolicySchema = Type.Union([
+  Type.Object({
+    type: Literal("host"),
+  }),
+  Type.Object({
+    type: Literal("plugin"),
+    resourceName: Type.String(),
+    resourceValue: Type.String(),
+  }),
+])
+
 export const clusterInfoSchema = Type.Object({
   id: Type.String(),
   name: Type.String(),
@@ -9,6 +21,15 @@ export const clusterInfoSchema = Type.Object({
   fqdn: Type.Optional(Type.String()),
   kubeApiServerIp: Type.Optional(Type.String()),
   kubeApiServerPort: Type.Optional(Type.Number()),
+
+  /**
+   * Specifies the policy for using the tun device inside containers.
+   *
+   * If not provided, the default policy is `host` which assumes just mounting /dev/net/tun from the host.
+   *
+   * For some runtimes, like Talos's one, the /dev/net/tun device is not available in the host, so the plugin policy should be used.
+   */
+  tunDevicePolicy: Type.Optional(tunDevicePolicySchema),
 })
 
 export const serviceTypeSchema = Type.StringEnum(["NodePort", "LoadBalancer", "ClusterIP"])
@@ -111,6 +132,17 @@ export const existingCluster = defineUnit({
 
   args: {
     ...sharedClusterArgs,
+
+    /**
+     * The policy for using the tun device inside containers.
+     *
+     * If not provided, the default policy is `host` which assumes just mounting /dev/net/tun from the host.
+     *
+     * For some runtimes, like Talos's one, the /dev/net/tun device is not available in the host, so the plugin policy should be used.
+     *
+     * @schema
+     */
+    tunDevicePolicy: Type.Optional(tunDevicePolicySchema),
   },
 
   secrets: {

package/src/mullvad.ts

@@ -1,5 +1,6 @@
 import { defineUnit, Type } from "@highstate/contract"
 import { networkEntity, peerEntity } from "./wireguard"
+import { l4EndpointEntity } from "./common"
 
 export const endpointType = Type.Union([
   Type.Literal("fqdn"),
@@ -13,6 +14,13 @@ export const peer = defineUnit({
   args: {
     hostname: Type.Optional(Type.String()),
     endpointType: Type.Optional({ ...endpointType, default: "fqdn" }),
+
+    /**
+     * Whether to include Mullvad DNS servers in the peer configuration.
+     *
+     * @schema
+     */
+    includeDns: Type.Default(Type.Boolean(), true),
   },
 
   inputs: {
@@ -29,6 +37,7 @@ export const peer = defineUnit({
 
   outputs: {
     peer: peerEntity,
+    l4Endpoint: l4EndpointEntity,
   },
 
   meta: {

package/src/obfuscators/index.ts

@@ -0,0 +1 @@
+export * as phantun from "./phantun"

package/src/obfuscators/phantun.ts

@@ -0,0 +1,36 @@
+import { defineUnit } from "@highstate/contract"
+import { deobfuscatorSpec, obfuscatorSpec } from "./shared"
+
+export const deobfuscator = defineUnit({
+  type: "obfuscators.phantun.deobfuscator",
+  ...deobfuscatorSpec,
+
+  meta: {
+    displayName: "Phantun Deobfuscator",
+    description: "The Phantun Deobfuscator deployed on Kubernetes.",
+    primaryIcon: "mdi:network-outline",
+    secondaryIcon: "mdi:hide",
+  },
+
+  source: {
+    package: "@highstate/obfuscators",
+    path: "phantun/deobfuscator",
+  },
+})
+
+export const obfuscator = defineUnit({
+  type: "obfuscators.phantun.obfuscator",
+  ...obfuscatorSpec,
+
+  meta: {
+    displayName: "Phantun Obfuscator",
+    description: "The Phantun Obfuscator deployed on Kubernetes.",
+    primaryIcon: "mdi:network-outline",
+    secondaryIcon: "mdi:hide",
+  },
+
+  source: {
+    package: "@highstate/obfuscators",
+    path: "phantun/obfuscator",
+  },
+})

package/src/obfuscators/shared.ts

@@ -0,0 +1,82 @@
+import { Type } from "@sinclair/typebox"
+import { clusterEntity } from "../k8s"
+import { l4EndpointEntity } from "../common"
+
+export const deobfuscatorSpec = {
+  args: {
+    /**
+     * The L4 endpoint to forward deobfuscated traffic to.
+     *
+     * Will take precedence over the `targetEndpoint` input.
+     *
+     * @schema
+     */
+    targetEndpoint: Type.Optional(Type.String()),
+  },
+
+  inputs: {
+    /**
+     * The Kubernetes cluster to deploy the deobfuscator on.
+     *
+     * @schema
+     */
+    k8sCluster: clusterEntity,
+
+    /**
+     * The L4 endpoint to forward deobfuscated traffic to.
+     *
+     * @schema
+     */
+    targetEndpoint: l4EndpointEntity,
+  },
+
+  outputs: {
+    /**
+     * The L4 endpoint of the deobfuscator accepting obfuscated traffic.
+     *
+     * @schema
+     */
+    endpoint: l4EndpointEntity,
+  },
+}
+
+export const obfuscatorSpec = {
+  args: {
+    /**
+     * The endpoint of the deobfuscator to pass obfuscated traffic to.
+     *
+     * Will take precedence over the `l4Endpoint` input.
+     *
+     * @schema
+     */
+    endpoint: Type.Optional(Type.String()),
+  },
+
+  inputs: {
+    /**
+     * The Kubernetes cluster to deploy the obfuscator on.
+     *
+     * @schema
+     */
+    k8sCluster: clusterEntity,
+
+    /**
+     * The L4 endpoint of the deobfuscator to pass obfuscated traffic to.
+     *
+     * @schema
+     */
+    endpoint: {
+      entity: l4EndpointEntity,
+      required: false,
+    },
+  },
+
+  outputs: {
+    /**
+     * The L4 endpoint accepting unobfuscated traffic.
+     *
+     * @schema
+     */
+    entryEndpoint: l4EndpointEntity,
+  },
+}

package/src/talos.ts

@@ -26,6 +26,8 @@ export const cluster = defineUnit({
      * Allow scheduling workloads on the master nodes.
      *
      * By default, "true" if no worker nodes are provided.
+     *
+     * @schema
      */
     scheduleOnMasters: Type.Boolean(),
 
@@ -33,6 +35,8 @@ export const cluster = defineUnit({
      * The endpoint of the cluster.
      *
      * By default, the first master node's endpoint is used.
+     *
+     * @schema
      */
     endpoint: Type.Optional(Type.String()),
 
@@ -40,6 +44,8 @@ export const cluster = defineUnit({
      * The name of the cluster.
      *
      * By default, the name of the instance is used.
+     *
+     * @schema
      */
     clusterName: Type.Optional(Type.String()),
 
@@ -52,8 +58,10 @@ export const cluster = defineUnit({
      * - "none" (disable CNI, must be installed manually)
      *
      * The "cilium" CNI plugin is recommended to cover advanced network policies like FQDNs.
+     *
+     * @schema
      */
-    cni: { ...cniSchema, default: "cilium" },
+    cni: Type.Default(cniSchema, "cilium"),
 
     /**
      * The CSI plugin to use.
@@ -61,24 +69,32 @@ export const cluster = defineUnit({
      * The following options are available:
      * - "local-path-provisioner" (default)
      * - "none" (disable CSI, must be installed manually if needed)
+     *
+     * @schema
      */
-    csi: { ...csiSchema, default: "local-path-provisioner" },
+    csi: Type.Default(csiSchema, "local-path-provisioner"),
 
     /**
      * The shared configuration patch.
      * It will be applied to all nodes.
+     *
+     * @schema
      */
     sharedConfigPatch: Type.Optional(Type.Record(Type.String(), Type.Any())),
 
     /**
      * The master configuration patch.
      * It will be applied to all master nodes.
+     *
+     * @schema
      */
     masterConfigPatch: Type.Optional(Type.Record(Type.String(), Type.Any())),
 
     /**
      * The worker configuration patch.
      * It will be applied to all worker nodes.
+     *
+     * @schema
      */
     workerConfigPatch: Type.Optional(Type.Record(Type.String(), Type.Any())),
   },

package/src/wireguard.ts

@@ -8,6 +8,7 @@ import {
   statefulSetEntity,
 } from "./k8s"
 import { providerEntity } from "./dns"
+import { l4EndpointEntity } from "./common"
 
 export const backendSchema = Type.StringEnum(["wireguard", "amneziawg"])
 export const presharedKeyModeSchema = Type.StringEnum(["none", "global", "secure"])
@@ -101,7 +102,7 @@ export const network = defineUnit({
      *
      * @schema
      */
-    backend: backendSchema,
+    backend: Type.Default(backendSchema, "wireguard"),
 
     /**
      * The option which defines how to handle pre-shared keys between peers.
@@ -284,7 +285,7 @@ export const peer = defineUnit({
      *
      * @schema
      */
-    publicKey: Type.String(),
+    publicKey: Type.Optional(Type.String()),
   },
 
   inputs: {
@@ -299,6 +300,28 @@ export const peer = defineUnit({
       entity: networkEntity,
       required: false,
     },
+
+    /**
+     * The existing WireGuard peer to extend.
+     *
+     * @schema
+     */
+    peer: {
+      entity: peerEntity,
+      required: false,
+    },
+
+    /**
+     * The L4 endpoint of the peer.
+     *
+     * Will take priority over all calculated endpoints if provided.
+     *
+     * @schema
+     */
+    l4Endpoint: {
+      entity: l4EndpointEntity,
+      required: false,
+    },
   },
 
   outputs: {
@@ -349,6 +372,8 @@ export const identity = defineUnit({
      *
      * 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()),
@@ -365,7 +390,7 @@ export const identity = defineUnit({
     fqdn: Type.Optional(Type.String()),
 
     /**
-     * Whether to register the FQDN of the identity with the DNS provider.
+     * Whether to register the FQDN of the identity with the matching DNS providers.
      *
      * By default, `true`.
      *
@@ -424,21 +449,46 @@ export const identity = defineUnit({
      * 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,
     },
 
-    dnsProvider: {
+    /**
+     * 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,
     },
   },
 
   outputs: {
     identity: identityEntity,
     peer: peerEntity,
+
+    l4Endpoint: {
+      entity: l4EndpointEntity,
+      required: false,
+    },
   },
 
   meta: {

package/src/xt-wgobfs.ts

@@ -1,49 +0,0 @@
-import { defineEntity, defineUnit, Type } from "@highstate/contract"
-import { endpointEntity } from "./common"
-
-export const channelEntity = defineEntity({
-  type: "xt-wgobfs.target",
-
-  schema: Type.Object({
-    endpoint: Type.String(),
-  }),
-})
-
-export const obfuscatorNode = defineUnit({
-  type: "xt-wgobfs.obfuscator",
-
-  outputs: {
-    outerCircuit: endpointEntity,
-    channel: channelEntity,
-  },
-
-  source: {
-    package: "@highstate/xt-wgobfs",
-    path: "target-node",
-  },
-
-  meta: {
-    displayName: "xt-wgobfs Deobfuscator",
-  },
-})
-
-export const deobfuscatorNode = defineUnit({
-  type: "xt-wgobfs.deobfuscator",
-
-  inputs: {
-    channel: channelEntity,
-  },
-
-  outputs: {
-    outerCircuit: endpointEntity,
-  },
-
-  source: {
-    package: "@highstate/xt-wgobfs",
-    path: "source-node",
-  },
-
-  meta: {
-    displayName: "xt-wgobfs Obfuscator",
-  },
-})