@highstate/library 0.20.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highstate/library",
-  "version": "0.20.0",
+  "version": "0.25.0",
   "type": "module",
   "highstate": {
     "type": "library"
@@ -23,23 +23,23 @@
       "stdlib"
     ]
   },
+  "scripts": {
+    "build": "highstate build",
+    "typecheck": "tsgo --noEmit --skipLibCheck",
+    "biome": "biome check --write --unsafe --error-on-warnings",
+    "biome:check": "biome check --error-on-warnings"
+  },
   "dependencies": {
-    "remeda": "^2.21.0",
-    "@highstate/contract": "0.20.0"
+    "@highstate/contract": "0.25.0",
+    "remeda": "^2.21.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.2.0",
+    "@highstate/cli": "0.25.0",
     "@typescript/native-preview": "^7.0.0-dev.20250920.1",
-    "type-fest": "^4.41.0",
-    "@highstate/cli": "0.20.0"
+    "type-fest": "^4.41.0"
   },
   "repository": {
     "url": "https://github.com/highstate-io/highstate"
-  },
-  "scripts": {
-    "build": "highstate build",
-    "typecheck": "tsgo --noEmit --skipLibCheck",
-    "biome": "biome check --write --unsafe --error-on-warnings",
-    "biome:check": "biome check --error-on-warnings"
   }
-}
+}

package/src/abbreviations.ts

@@ -16,6 +16,8 @@ registerKnownAbbreviations([
   "TLS",
   "HTTP",
   "HTTPS",
+  "ALB",
+  "NLB",
   "TCP",
   "UDP",
   "CIDR",

package/src/apps/index.ts

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

package/src/apps/vault.ts

@@ -0,0 +1,374 @@
+import {
+  defineEntity,
+  defineUnit,
+  type EntityInput,
+  type EntityValue,
+  secretSchema,
+  z,
+} from "@highstate/contract"
+import { fileEntity } from "../common"
+import { l7EndpointContainer } from "../network"
+import { privateKeySchema } from "../tls"
+
+const vaultColor = "#6F5CFF"
+const vaultIcon = "simple-icons:vault"
+
+export const credentialsSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("token"),
+
+    /**
+     * The static token used to authenticate against Vault.
+     */
+    token: secretSchema(z.string()),
+  }),
+
+  z.object({
+    type: z.literal("approle"),
+
+    /**
+     * The path where the AppRole auth backend is mounted.
+     */
+    authPath: z.string(),
+
+    /**
+     * The role ID used to authenticate against Vault.
+     */
+    roleId: z.string(),
+
+    /**
+     * The secret ID used to authenticate against Vault.
+     */
+    secretId: secretSchema(z.string()),
+  }),
+])
+
+/**
+ * Represents a connection to a Vault instance, including the endpoints and credentials.
+ */
+export const connectionEntity = defineEntity({
+  type: "vault.connection.v1",
+
+  extends: { l7EndpointContainer },
+
+  includes: {
+    /**
+     * The CA certificate file used to verify the server if any.
+     */
+    ca: {
+      entity: fileEntity,
+      required: false,
+    },
+  },
+
+  schema: z.object({
+    /**
+     * The credentials for authenticating to the Vault instance.
+     */
+    credentials: credentialsSchema,
+
+    /**
+     * The Vault Enterprise namespace to operate in.
+     */
+    namespace: z.string().optional(),
+
+    /**
+     * The TLS server name used to verify the Vault server certificate.
+     */
+    tlsServerName: z.string().optional(),
+  }),
+
+  meta: {
+    color: vaultColor,
+    title: "Vault Connection",
+    icon: vaultIcon,
+    iconColor: vaultColor,
+  },
+})
+
+export const pkiCaEntity = defineEntity({
+  type: "vault.pki.ca.v1",
+
+  includes: {
+    /**
+     * The Vault connection authorized to manage this PKI CA.
+     */
+    connection: {
+      entity: connectionEntity,
+    },
+
+    /**
+     * The root CA certificate in PEM format.
+     */
+    ca: {
+      entity: fileEntity,
+    },
+  },
+
+  schema: z.object({
+    /**
+     * The mount path of the root PKI backend.
+     */
+    path: z.string(),
+
+    /**
+     * The mount path of the intermediate PKI backend used by issuers.
+     */
+    intermediatePath: z.string(),
+
+    /**
+     * The common name of the root CA certificate.
+     */
+    commonName: z.string(),
+  }),
+
+  meta: {
+    color: vaultColor,
+    title: "Vault PKI CA",
+    icon: vaultIcon,
+    iconColor: vaultColor,
+  },
+})
+
+export const pkiIssuerEntity = defineEntity({
+  type: "vault.pki.issuer.v1",
+
+  includes: {
+    /**
+     * The Vault connection authorized to issue certificates through this PKI issuer.
+     */
+    connection: {
+      entity: connectionEntity,
+    },
+  },
+
+  schema: z.object({
+    /**
+     * The mount path of the shared intermediate PKI backend.
+     */
+    path: z.string(),
+
+    /**
+     * The PKI role name used to issue leaf certificates.
+     */
+    roleName: z.string(),
+
+    /**
+     * The DNS zones for which this issuer can issue certificates.
+     */
+    dnsNames: z.string().array(),
+
+    /**
+     * The common names for which this issuer can issue certificates.
+     */
+    commonNames: z.string().array(),
+
+    /**
+     * Whether the Vault role allows issuing certificates for exact allowed domains.
+     */
+    allowBareDomains: z.boolean(),
+
+    /**
+     * Whether the Vault role allows issuing certificates for subdomains of allowed domains.
+     */
+    allowSubdomains: z.boolean(),
+
+    /**
+     * Whether the Vault role allows issuing wildcard certificates.
+     */
+    allowWildcardCertificates: z.boolean(),
+  }),
+
+  meta: {
+    color: vaultColor,
+    title: "Vault PKI Issuer",
+    icon: vaultIcon,
+    iconColor: vaultColor,
+  },
+})
+
+/**
+ * Creates a root PKI CA in Vault.
+ */
+export const pkiCa = defineUnit({
+  type: "vault.pki.ca.v1",
+
+  args: {
+    /**
+     * The mount path of the root PKI backend.
+     *
+     * If not provided, it will be set to `pki/<unit name>`.
+     */
+    path: z.string().optional(),
+
+    /**
+     * The common name of the root CA certificate.
+     *
+     * If not provided, it will be set to `<unit name> Root CA`.
+     */
+    commonName: z.string().optional(),
+
+    /**
+     * The TTL of the generated root CA certificate.
+     */
+    ttl: z.string().default("87600h"),
+
+    /**
+     * The private key configuration for the root CA certificate.
+     */
+    privateKey: privateKeySchema,
+
+    /**
+     * The default lease TTL of the root PKI backend in seconds.
+     */
+    defaultLeaseTtlSeconds: z.number().int().positive().default(3600),
+
+    /**
+     * The maximum lease TTL of the root PKI backend in seconds.
+     */
+    maxLeaseTtlSeconds: z.number().int().positive().default(315360000),
+
+    /**
+     * The intermediate PKI backend and CA certificate configuration.
+     */
+    intermediate: z
+      .object({
+        /**
+         * The mount path of the intermediate PKI backend used by issuers.
+         *
+         * If not provided, it will be set to `<root path>-intermediate`.
+         */
+        path: z.string().optional(),
+
+        /**
+         * The common name of the intermediate CA certificate.
+         *
+         * If not provided, it will be set to `<unit name> Intermediate CA`.
+         */
+        commonName: z.string().optional(),
+
+        /**
+         * The TTL of the generated intermediate CA certificate.
+         */
+        ttl: z.string().default("43800h"),
+
+        /**
+         * The private key configuration for the intermediate CA certificate.
+         */
+        privateKey: privateKeySchema,
+
+        /**
+         * The default lease TTL of the intermediate PKI backend in seconds.
+         */
+        defaultLeaseTtlSeconds: z.number().int().positive().default(3600),
+
+        /**
+         * The maximum lease TTL of the intermediate PKI backend in seconds.
+         */
+        maxLeaseTtlSeconds: z.number().int().positive().default(157680000),
+      })
+      .default({
+        ttl: "43800h",
+        privateKey: {
+          algorithm: "RSA",
+          size: 4096,
+        },
+        defaultLeaseTtlSeconds: 3600,
+        maxLeaseTtlSeconds: 157680000,
+      }),
+  },
+
+  inputs: {
+    /**
+     * The Vault connection used to configure the root PKI CA.
+     */
+    connection: connectionEntity,
+  },
+
+  outputs: {
+    ca: pkiCaEntity,
+  },
+
+  meta: {
+    title: "Vault PKI CA",
+    icon: "simple-icons:vault",
+    category: "Security",
+  },
+
+  source: {
+    package: "@highstate/vault",
+    path: "units/pki-ca",
+  },
+})
+
+/**
+ * Creates a PKI issuer role in Vault.
+ */
+export const pkiIssuer = defineUnit({
+  type: "vault.pki.issuer.v1",
+
+  args: {
+    /**
+     * The PKI role name used to issue leaf certificates.
+     *
+     * If not provided, it will be set to the unit name.
+     */
+    roleName: z.string().optional(),
+
+    /**
+     * The DNS zones for which this issuer can issue certificates.
+     */
+    dnsNames: z.string().array(),
+
+    /**
+     * The common names for which this issuer can issue certificates.
+     */
+    commonNames: z.string().array().default([]),
+
+    /**
+     * Whether the Vault role allows issuing certificates for exact allowed domains.
+     */
+    allowBareDomains: z.boolean().default(true),
+
+    /**
+     * Whether the Vault role allows issuing certificates for subdomains of allowed domains.
+     */
+    allowSubdomains: z.boolean().default(true),
+
+    /**
+     * Whether the Vault role allows issuing wildcard certificates.
+     */
+    allowWildcardCertificates: z.boolean().default(true),
+  },
+
+  inputs: {
+    /**
+     * The Vault PKI CA used to create and sign the intermediate issuer.
+     */
+    ca: pkiCaEntity,
+  },
+
+  outputs: {
+    issuer: pkiIssuerEntity,
+  },
+
+  meta: {
+    title: "Vault PKI Issuer",
+    icon: "simple-icons:vault",
+    category: "Security",
+  },
+
+  source: {
+    package: "@highstate/vault",
+    path: "units/pki-issuer",
+  },
+})
+
+export type Connection = EntityValue<typeof connectionEntity>
+export type ConnectionInput = EntityInput<typeof connectionEntity>
+
+export type PkiCa = EntityValue<typeof pkiCaEntity>
+export type PkiCaInput = EntityInput<typeof pkiCaEntity>
+
+export type PkiIssuer = EntityValue<typeof pkiIssuerEntity>
+export type PkiIssuerInput = EntityInput<typeof pkiIssuerEntity>

package/src/common/access-point.ts

@@ -8,6 +8,56 @@ import {
 import * as dns from "../dns"
 import { implementationReferenceSchema } from "../impl-ref"
 import { l3EndpointEntity } from "../network"
+import { booleanPatchSchema } from "../utils"
+import { fileEntity } from "./files"
+
+const gatewayClientAuthSchema = z.object({
+  /**
+   * The PEM-encoded CA certificates used to validate client certificates.
+   */
+  ca: z.string().array(),
+
+  /**
+   * The DNS SAN patterns to validate on client certificates.
+   */
+  dnsNames: z.string().array().default([]),
+})
+
+const gatewayPatchArgs = {
+  /**
+   * The public L3 endpoints to set on the gateway.
+   *
+   * If not specified, the existing endpoints will be kept.
+   */
+  endpoints: z.string().array().default([]),
+
+  /**
+   * The DNS SAN patterns to validate on client certificates.
+   */
+  clientAuthDnsNames: z.string().array().default([]),
+}
+
+const gatewayPatchInputs = {
+  /**
+   * The public L3 endpoints to set on the gateway.
+   *
+   * These endpoints take precedence over the endpoints argument.
+   */
+  endpoints: {
+    entity: l3EndpointEntity,
+    required: false,
+    multiple: true,
+  },
+
+  /**
+   * The CA certificate files used to validate client certificates.
+   */
+  clientAuthCa: {
+    entity: fileEntity,
+    required: false,
+    multiple: true,
+  },
+} as const
 
 export const gatewayEntity = defineEntity({
   type: "common.gateway.v1",
@@ -24,6 +74,11 @@ export const gatewayEntity = defineEntity({
      * If not provided, should be automatically detected by the implementation.
      */
     endpoints: l3EndpointEntity.schema.array().default([]),
+
+    /**
+     * The default client certificate validation configuration for routes using this gateway.
+     */
+    clientAuth: gatewayClientAuthSchema.optional(),
   }),
 
   meta: {
@@ -60,22 +115,30 @@ export const tlsIssuerEntity = defineEntity({
 export const accessPointEntity = defineEntity({
   type: "common.access-point.v1",
 
-  schema: z.object({
+  includes: {
     /**
      * The gateway of the access point.
      */
-    gateway: gatewayEntity.schema,
+    gateway: gatewayEntity,
 
     /**
      * The TLS issuers used to manage TLS certificates for the access point.
      */
-    tlsIssuers: tlsIssuerEntity.schema.array(),
+    tlsIssuers: {
+      entity: tlsIssuerEntity,
+      multiple: true,
+    },
 
     /**
      * The DNS providers used to manage the DNS records for the access point.
      */
-    dnsProviders: dns.providerEntity.schema.array(),
+    dnsProviders: {
+      entity: dns.providerEntity,
+      multiple: true,
+    },
+  },
 
+  schema: z.object({
     /**
      * Whether the DNS records created for the access point should be proxied.
      */
@@ -140,6 +203,89 @@ export const accessPoint = defineUnit({
   },
 })
 
+/**
+ * Patches some properties of the gateway and outputs the updated gateway.
+ */
+export const gatewayPatch = defineUnit({
+  type: "common.gateway-patch.v1",
+
+  args: gatewayPatchArgs,
+
+  inputs: {
+    gateway: gatewayEntity,
+    ...gatewayPatchInputs,
+  },
+
+  outputs: {
+    gateway: gatewayEntity,
+  },
+
+  meta: {
+    title: "Gateway Patch",
+    icon: "mdi:router-network",
+    secondaryIcon: "fluent:patch-20-filled",
+    category: "Kubernetes",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/gateway-patch",
+  },
+})
+
+/**
+ * Patches some properties of the access point and outputs the updated access point.
+ */
+export const accessPointPatch = defineUnit({
+  type: "common.access-point-patch.v1",
+
+  args: {
+    ...gatewayPatchArgs,
+
+    /**
+     * Whether the DNS records created for the access point should be proxied.
+     *
+     * If not specified, the existing value will be kept.
+     */
+    proxied: booleanPatchSchema,
+  },
+
+  inputs: {
+    accessPoint: accessPointEntity,
+    gateway: {
+      entity: gatewayEntity,
+      required: false,
+    },
+    tlsIssuers: {
+      entity: tlsIssuerEntity,
+      required: false,
+      multiple: true,
+    },
+    dnsProviders: {
+      entity: dns.providerEntity,
+      required: false,
+      multiple: true,
+    },
+    ...gatewayPatchInputs,
+  },
+
+  outputs: {
+    accessPoint: accessPointEntity,
+  },
+
+  meta: {
+    title: "Access Point Patch",
+    icon: "mdi:access-point",
+    secondaryIcon: "fluent:patch-20-filled",
+    category: "Kubernetes",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/access-point-patch",
+  },
+})
+
 export type Gateway = EntityValue<typeof gatewayEntity>
 export type AccessPoint = EntityValue<typeof accessPointEntity>
 export type TlsIssuer = EntityValue<typeof tlsIssuerEntity>

package/src/common/filter.ts

@@ -0,0 +1,40 @@
+import { defineUnit, objectEntity, z } from "@highstate/contract"
+
+/**
+ * A unit that filters entities based on a specified expression.
+ */
+export const filter = defineUnit({
+  type: "common.filter.v1",
+
+  args: {
+    /**
+     * The expression used to filter entities.
+     */
+    expression: z.string(),
+  },
+
+  inputs: {
+    entities: {
+      entity: objectEntity,
+      multiple: true,
+    },
+  },
+
+  outputs: {
+    entities: {
+      fromInput: "entities",
+      multiple: true,
+    },
+  },
+
+  meta: {
+    title: "Entity Filter",
+    category: "common",
+    icon: "mdi:filter-variant",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "filter",
+  },
+})

package/src/common/index.ts

@@ -1,3 +1,4 @@
 export * from "./access-point"
 export * from "./files"
+export * from "./filter"
 export * from "./server"