@highstate/library 0.7.11 → 0.9.0

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/k3s.ts

@@ -1,16 +1,24 @@
 import { defineUnit } from "@highstate/contract"
+import { Type } from "@sinclair/typebox"
 import { serverEntity } from "./common"
 import { clusterEntity, sharedClusterArgs } from "./k8s"
+import { providerEntity } from "./dns"
 
 export const cluster = defineUnit({
   type: "k3s.cluster",
 
   args: {
     ...sharedClusterArgs,
+    config: Type.Optional(Type.Record(Type.String(), Type.Any())),
   },
 
   inputs: {
     server: serverEntity,
+    dnsProviders: {
+      entity: providerEntity,
+      required: false,
+      multiple: true,
+    },
   },
 
   outputs: {

package/src/k8s.ts

@@ -1,11 +1,35 @@
 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(),
   cni: Type.Optional(Type.String()),
   externalIps: Type.Array(Type.String()),
+  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"])
@@ -108,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: {
@@ -168,15 +203,16 @@ export const tlsIssuerEntity = defineEntity({
 })
 
 export const accessPointEntity = defineEntity({
-  type: "common.access-point",
+  type: "k8s.access-point",
+
   schema: Type.Object({
     gateway: gatewayEntity.schema,
     tlsIssuer: tlsIssuerEntity.schema,
-    dnsProvider: providerEntity.schema,
+    dnsProviders: Type.Array(providerEntity.schema),
   }),
 
   meta: {
-    color: "#FFC107",
+    color: "#F57F17",
   },
 })
 
@@ -186,7 +222,10 @@ export const accessPoint = defineUnit({
   inputs: {
     gateway: gatewayEntity,
     tlsIssuer: tlsIssuerEntity,
-    dnsProvider: providerEntity,
+    dnsProviders: {
+      entity: providerEntity,
+      multiple: true,
+    },
   },
 
   outputs: {
@@ -231,9 +270,23 @@ export const certManager = defineUnit({
 export const dns01TlsIssuer = defineUnit({
   type: "k8s.dns01-issuer",
 
+  args: {
+    /**
+     * The top-level domains to filter the DNS01 challenge for.
+     *
+     * If not provided, will use all domains passed to the DNS providers.
+     *
+     * @schema
+     */
+    domains: Type.Optional(Type.Array(Type.String())),
+  },
+
   inputs: {
     k8sCluster: clusterEntity,
-    dnsProvider: providerEntity,
+    dnsProviders: {
+      entity: providerEntity,
+      multiple: true,
+    },
   },
 
   outputs: {
@@ -333,6 +386,30 @@ export const interfaceEntity = defineEntity({
   },
 })
 
+export const gatewayApi = defineUnit({
+  type: "k8s.gateway-api",
+
+  inputs: {
+    k8sCluster: clusterEntity,
+  },
+
+  outputs: {
+    k8sCluster: clusterEntity,
+  },
+
+  meta: {
+    displayName: "Gateway API",
+    description: "Installs the Gateway API CRDs to the cluster.",
+    primaryIcon: "mdi:kubernetes",
+    primaryIconColor: "#4CAF50",
+  },
+
+  source: {
+    package: "@highstate/k8s",
+    path: "units/gateway-api",
+  },
+})
+
 export type ClusterInfo = Static<typeof clusterInfoSchema>
 export type Cluster = Static<typeof clusterEntity.schema>
 

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/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()),
@@ -357,11 +382,21 @@ export const identity = defineUnit({
      * The FQDN of the WireGuard identity.
      * Will be used as endpoint for the peer.
      *
-     * If `dnsProvider` is provided and `externalIp` is available, the FQDN will be registered automatically.
+     * 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),
   },
 
   secrets: {
@@ -410,15 +445,50 @@ export const identity = defineUnit({
       required: false,
     },
 
-    dnsProvider: {
+    /**
+     * 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,
     },
   },
 
   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",
-  },
-})