@highstate/common 0.9.18 → 0.9.19

package/src/shared/network.ts

@@ -1,5 +1,5 @@
 import type { ArrayPatchMode, network } from "@highstate/library"
-import { toPromise, type Input } from "@highstate/pulumi"
+import { type Input, toPromise } from "@highstate/pulumi"
 import { uniqueBy } from "remeda"
 
 /**
@@ -276,11 +276,14 @@ export function l3EndpointToL4(
  *
  * @returns The filtered list of endpoints.
  */
-export function filterEndpoints<TEndpoint extends network.L34Endpoint>(
+export function filterEndpoints<
+  TEndpoint extends network.L34Endpoint,
+  TType extends network.L34Endpoint["type"],
+>(
   endpoints: TEndpoint[],
   filter?: network.EndpointFilter,
-  types?: network.L34Endpoint["type"][],
-): TEndpoint[] {
+  types?: TType[],
+): (TEndpoint & { type: TType })[] {
   if (filter?.length) {
     endpoints = endpoints.filter(endpoint => filter.includes(endpoint.visibility))
   } else if (endpoints.some(endpoint => endpoint.visibility === "public")) {
@@ -289,11 +292,11 @@ export function filterEndpoints<TEndpoint extends network.L34Endpoint>(
     endpoints = endpoints.filter(endpoint => endpoint.visibility === "external")
   }
 
-  if (types && types.length) {
-    endpoints = endpoints.filter(endpoint => types.includes(endpoint.type))
+  if (types?.length) {
+    endpoints = endpoints.filter(endpoint => types.includes(endpoint.type as TType))
   }
 
-  return endpoints
+  return endpoints as (TEndpoint & { type: TType })[]
 }
 
 /**
@@ -369,31 +372,42 @@ export function parseL7Endpoint(l7Endpoint: InputL7Endpoint): network.L7Endpoint
  * @param endpoints The new endpoints to add in string format.
  * @param inputEndpoints The input endpoints to add in object format.
  * @param mode The mode to use when updating the endpoints. Can be "replace" or "prepend". Defaults to "prepend".
- *
- * @returns The updated list of endpoints.
+ * @returns The updated list of endpoints with duplicates removed.
  */
-export async function updateEndpoints<TEdnpoints extends network.L34Endpoint>(
-  currentEndpoints: Input<TEdnpoints[]>,
-  endpoints: string[],
-  inputEndpoints: Input<TEdnpoints[]>,
+export async function updateEndpoints<TEndpoints extends network.L34Endpoint>(
+  currentEndpoints: Input<TEndpoints[]>,
+  endpoints: string[] | undefined,
+  inputEndpoints: Input<TEndpoints[]> | undefined,
   mode: ArrayPatchMode = "prepend",
-): Promise<TEdnpoints[]> {
+): Promise<TEndpoints[]> {
   const resolvedCurrentEndpoints = await toPromise(currentEndpoints)
-  const resolvedInputEndpoints = await toPromise(inputEndpoints)
-
-  const newEndpoints = uniqueBy(
-    //
-    [...endpoints.map(parseL34Endpoint), ...resolvedInputEndpoints],
-    endpoint => l34EndpointToString(endpoint),
-  )
+  const newEndpoints = await parseEndpoints(endpoints, inputEndpoints)
 
   if (mode === "replace") {
-    return newEndpoints as TEdnpoints[]
+    return newEndpoints as TEndpoints[]
   }
 
   return uniqueBy(
-    //
     [...newEndpoints, ...resolvedCurrentEndpoints],
-    endpoint => l34EndpointToString(endpoint),
-  ) as TEdnpoints[]
+    l34EndpointToString,
+  ) as TEndpoints[]
+}
+
+/**
+ * Parses a list of endpoints from strings and input objects.
+ *
+ * @param endpoints The list of endpoint strings to parse.
+ * @param inputEndpoints The list of input endpoint objects to use.
+ * @returns The parsed list of endpoint objects with duplicates removed.
+ */
+export async function parseEndpoints<TEndpoints extends network.L34Endpoint>(
+  endpoints: string[] | undefined,
+  inputEndpoints: Input<TEndpoints[]> | undefined,
+): Promise<TEndpoints[]> {
+  const resolvedInputEndpoints = await toPromise(inputEndpoints)
+
+  return uniqueBy(
+    [...(endpoints?.map(parseL34Endpoint) ?? []), ...(resolvedInputEndpoints ?? [])],
+    l34EndpointToString,
+  ) as TEndpoints[]
 }

package/src/shared/passwords.ts

@@ -6,7 +6,7 @@ import { secureMask } from "micro-key-producer/password.js"
  *
  * It uses "Safari Keychain Secure Password" format.
  *
- * The approximate entropy is 71 bits (https://support.apple.com/guide/security/automatic-strong-passwords-secc84c811c4/web).
+ * The approximate entropy is [71 bits](https://support.apple.com/guide/security/automatic-strong-passwords-secc84c811c4/web).
  */
 export function generatePassword(): string {
   return secureMask.apply(randomBytes(32)).password
@@ -19,13 +19,13 @@ type KeyFormatMap = {
 }
 
 /**
- * Generates a secure random key strong enough for online use such as encryption.
+ * Generates a secure random key strong enough for offline use such as encryption.
  *
  * The strong entropy is 256 bits.
  *
  * @param format The format of the generated key. By default, it is "hex".
  */
-export function generateKey<TFormat extends keyof KeyFormatMap>(
+export function generateKey<TFormat extends keyof KeyFormatMap = "hex">(
   format: TFormat = "hex" as TFormat,
 ): KeyFormatMap[TFormat] {
   const bytes = randomBytes(32)

package/src/shared/ssh.ts

@@ -1,13 +1,12 @@
-import type { common, network, ssh } from "@highstate/library"
+import { stripNullish, type UnitTerminal } from "@highstate/contract"
+import type { ssh, common, network } from "@highstate/library"
 import {
-  ensureSecretValue,
+  fileFromString,
   output,
-  Output,
+  type Output,
   secret,
   toPromise,
   type Input,
-  type InstanceTerminal,
-  type UnitSecret,
 } from "@highstate/pulumi"
 import getKeys, { PrivateExport } from "micro-key-producer/ssh.js"
 import { randomBytes } from "micro-key-producer/utils.js"
@@ -16,71 +15,60 @@ import * as images from "../../assets/images.json"
 import { l3EndpointToString, l3EndpointToL4 } from "./network"
 import { Command } from "./command"
 
-export function createSshTerminal(
-  credentials: Input<ssh.Credentials | undefined>,
-): Output<InstanceTerminal | undefined> {
-  return output(credentials).apply(credentials => {
-    if (!credentials) {
-      return undefined
-    }
+export async function createSshTerminal(
+  credentials: Input<ssh.Connection>,
+): Promise<Output<UnitTerminal>> {
+  const resolvedCredentials = await toPromise(credentials)
 
-    const command = ["ssh", "-tt", "-o", "UserKnownHostsFile=/known_hosts"]
+  const command = ["ssh", "-tt", "-o", "UserKnownHostsFile=/known_hosts"]
 
-    // TODO: select best endpoint based on the environment
-    const endpoint = credentials.endpoints[0]
+  // TODO: select best endpoint based on the environment
+  const endpoint = resolvedCredentials.endpoints[0]
 
-    command.push("-p", endpoint.port.toString())
+  command.push("-p", endpoint.port.toString())
 
-    if (credentials.keyPair) {
-      command.push("-i", "/private_key")
-    }
+  if (resolvedCredentials.keyPair) {
+    command.push("-i", "/private_key")
+  }
 
-    command.push(`${credentials.user}@${l3EndpointToString(endpoint)}`)
+  command.push(`${resolvedCredentials.user}@${l3EndpointToString(endpoint)}`)
 
-    if (credentials.password) {
-      command.unshift("sshpass", "-f", "/password")
-    }
+  if (resolvedCredentials.password) {
+    command.unshift("sshpass", "-f", "/password")
+  }
 
-    return {
-      name: "ssh",
+  return output({
+    name: "ssh",
 
-      meta: {
-        title: "Shell",
-        description: "Connect to the server via SSH",
-        icon: "gg:remote",
-      },
+    meta: {
+      title: "Shell",
+      description: "Connect to the server via SSH.",
+      icon: "gg:remote",
+    },
 
-      spec: {
-        image: images["terminal-ssh"].image,
-        command,
+    spec: {
+      image: images["terminal-ssh"].image,
+      command,
 
-        files: {
-          "/password": credentials.password,
+      files: stripNullish({
+        "/password": resolvedCredentials.password
+          ? fileFromString("password", resolvedCredentials.password, { isSecret: true })
+          : undefined,
 
-          "/private_key": credentials.keyPair?.privateKey && {
-            content: {
-              type: "embedded",
-              value: credentials.keyPair?.privateKey,
-            },
-            meta: {
-              name: "private_key",
+        "/private_key": resolvedCredentials.keyPair?.privateKey
+          ? fileFromString("private_key", resolvedCredentials.keyPair.privateKey, {
+              isSecret: true,
               mode: 0o600,
-            },
-          },
-
-          "/known_hosts": {
-            content: {
-              type: "embedded",
-              value: `${l3EndpointToString(endpoint)} ${credentials.hostKey}`,
-            },
-            meta: {
-              name: "known_hosts",
-              mode: 0o644,
-            },
-          },
-        },
-      },
-    } satisfies InstanceTerminal
+            })
+          : undefined,
+
+        "/known_hosts": fileFromString(
+          "known_hosts",
+          `${l3EndpointToString(endpoint)} ${resolvedCredentials.hostKey}`,
+          { mode: 0o644 },
+        ),
+      }),
+    },
   })
 }
 
@@ -90,10 +78,10 @@ export function createSshTerminal(
  *
  * @returns The generated SSH private key in PEM format.
  */
-export function generateSshPrivateKey(): string {
+export function generateSshPrivateKey(): Output<string> {
   const seed = randomBytes(32)
 
-  return getKeys(seed).privateKey
+  return secret(getKeys(seed).privateKey)
 }
 
 /**
@@ -120,25 +108,6 @@ export function sshPrivateKeyToKeyPair(privateKeyString: Input<string>): Output<
   })
 }
 
-/**
- * Ensures that the provided SSH key is available and generates a new key pair if not.
- * If an existing key pair is provided, it will be used instead of generating a new one.
- *
- * @param privateKey The secret containing the private key.
- * @param existingKeyPair An optional existing key pair to use if available.
- * @returns An Output of the KeyPair object.
- */
-export function ensureSshKeyPair(
-  privateKey: UnitSecret<string | undefined>,
-  existingKeyPair?: Input<ssh.KeyPair>,
-): Output<ssh.KeyPair> {
-  if (existingKeyPair) {
-    return output(existingKeyPair)
-  }
-
-  return ensureSecretValue(privateKey, generateSshPrivateKey).value.apply(sshPrivateKeyToKeyPair)
-}
-
 export type ServerOptions = {
   /**
    * The local name of the server to namespace resources.
@@ -158,41 +127,25 @@ export type ServerOptions = {
   endpoints: network.L3Endpoint[]
 
   /**
-   * The L4 endpoint of the server.
-   *
-   * If not provided, the first endpoint will be used + `sshPort`.
-   */
-  sshEndpoint?: network.L4Endpoint
-
-  /**
-   * The SSH port to use for the server.
-   *
-   * Will be ignored if `sshEndpoint` is provided.
-   */
-  sshPort?: number
-
-  /**
-   * The SSH user to use for the server.
+   * The arguments for the SSH connection.
    */
-  sshUser?: string
+  sshArgs?: Partial<ssh.Args>
 
   /**
-   * The SSH password to use for the server.
+   * The password for the SSH connection.
    */
-  sshPassword?: Input<string | undefined>
+  sshPassword?: Input<string>
 
   /**
-   * The SSH private key to use for the server.
+   * The private key for the SSH connection.
    */
   sshPrivateKey?: Input<string>
 
   /**
-   * Whether the server is expected to have SSH access.
-   * If false, the server will be created without SSH credentials.
-   *
-   * By default, this is true.
+   * The SSH key pair for the server.
+   * If provided, it will take precedence over the `sshPrivateKey` argument.
    */
-  hasSsh?: boolean
+  sshKeyPair?: Input<ssh.KeyPair>
 
   /**
    * Whether to wait for the server to respond to a ping command before returning.
@@ -224,7 +177,7 @@ export type ServerOptions = {
    *
    * If true, the command will wait for the SSH service to respond before proceeding.
    *
-   * By default, this is true if `hasSsh` is true.
+   * By default, this is true if `sshArgs.enabled` is true, otherwise false.
    */
   waitForSsh?: boolean
 
@@ -245,6 +198,36 @@ export type ServerOptions = {
   sshCheckTimeout?: number
 }
 
+export type ServerBundle = {
+  /**
+   * The server entity created with the provided options.
+   */
+  server: Output<common.Server>
+
+  /**
+   * The SSH terminal created for the server.
+   */
+  terminal?: Output<UnitTerminal>
+}
+
+/**
+ * Creates a server entity with the provided options and returns a bundle containing the server entity and terminal.
+ *
+ * Basically, it just a convenience function that calls `createServerEntity` and `createSshTerminal`.
+ *
+ * @param options The options for creating the server entity.
+ * @returns A promise that resolves to a ServerBundle containing the server entity and terminal.
+ */
+export async function createServerBundle(options: ServerOptions): Promise<ServerBundle> {
+  const server = await createServerEntity(options)
+  const ssh = await toPromise(server.ssh)
+
+  return {
+    server,
+    terminal: ssh ? await createSshTerminal(ssh) : undefined,
+  }
+}
+
 /**
  * Creates a server entity with the provided options.
  * It will create a command to check the SSH service and return the server entity.
@@ -256,25 +239,23 @@ export async function createServerEntity({
   name,
   fallbackHostname,
   endpoints,
-  sshEndpoint,
-  sshPort = 22,
-  sshUser = "root",
+  sshArgs = { enabled: true, port: 22, user: "root" },
   sshPassword,
   sshPrivateKey,
-  hasSsh = true,
+  sshKeyPair,
   pingInterval,
   pingTimeout,
   waitForPing,
   waitForSsh,
   sshCheckInterval,
   sshCheckTimeout,
-}: ServerOptions): Promise<common.Server> {
+}: ServerOptions): Promise<Output<common.Server>> {
   if (endpoints.length === 0) {
     throw new Error("At least one L3 endpoint is required to create a server entity")
   }
 
   fallbackHostname ??= name
-  waitForSsh ??= hasSsh
+  waitForSsh ??= sshArgs.enabled
   waitForPing ??= !waitForSsh
 
   if (waitForPing) {
@@ -287,19 +268,19 @@ export async function createServerEntity({
     }).wait()
   }
 
-  if (!hasSsh) {
-    return {
+  if (!sshArgs.enabled) {
+    return output({
       hostname: name,
       endpoints,
-    }
+    })
   }
 
-  sshEndpoint ??= l3EndpointToL4(endpoints[0], sshPort)
+  const sshHost = sshArgs?.host ?? l3EndpointToString(endpoints[0])
 
   if (waitForSsh) {
     await Command.waitFor(`${name}.ssh`, {
       host: "local",
-      create: `nc -zv ${l3EndpointToString(sshEndpoint)} ${sshPort}`,
+      create: `nc -zv ${sshHost} ${sshArgs.port}`,
       timeout: sshCheckTimeout ?? 300,
       interval: sshCheckInterval ?? 5,
       triggers: [Date.now()],
@@ -307,11 +288,11 @@ export async function createServerEntity({
   }
 
   const connection = output({
-    host: l3EndpointToString(sshEndpoint),
-    port: sshEndpoint.port,
-    user: sshUser,
+    host: sshHost,
+    port: sshArgs.port,
+    user: sshArgs.user,
     password: sshPassword,
-    privateKey: sshPrivateKey,
+    privateKey: sshKeyPair ? output(sshKeyPair).privateKey : sshPrivateKey,
     dialErrorLimit: 3,
   })
 
@@ -327,15 +308,19 @@ export async function createServerEntity({
     triggers: [Date.now()],
   })
 
-  return await toPromise({
+  return output({
     endpoints,
     hostname: hostnameResult.stdout.apply(x => x.trim()),
     ssh: {
-      endpoints: [sshEndpoint],
-      user: sshUser,
+      endpoints: [l3EndpointToL4(sshHost, sshArgs.port ?? 22)],
+      user: sshArgs.user ?? "root",
       hostKey: hostKeyResult.stdout.apply(x => x.trim()),
-      password: sshPassword,
-      keyPair: sshPrivateKey ? sshPrivateKeyToKeyPair(sshPrivateKey) : undefined,
+      password: connection.password,
+      keyPair: sshKeyPair
+        ? sshKeyPair
+        : sshPrivateKey
+          ? sshPrivateKeyToKeyPair(sshPrivateKey)
+          : undefined,
     },
   })
 }

package/src/shared/tls.ts

@@ -0,0 +1,123 @@
+import type { common } from "@highstate/library"
+import { getOrCreate, z } from "@highstate/contract"
+import {
+  ComponentResource,
+  type ComponentResourceOptions,
+  type Input,
+  type InputArray,
+  normalizeInputs,
+  type Output,
+  output,
+  Resource,
+} from "@highstate/pulumi"
+import { ImplementationMediator } from "./impl-ref"
+
+export const tlsCertificateMediator = new ImplementationMediator(
+  "tls-certificate",
+  z.object({
+    name: z.string(),
+    spec: z.custom<TlsCertificateSpec>(),
+    opts: z.custom<ComponentResourceOptions>().optional(),
+  }),
+  z.instanceof(Resource),
+)
+
+export type TlsCertificateSpec = {
+  /**
+   * The common name for the certificate.
+   */
+  commonName?: Input<string>
+
+  /**
+   * The alternative DNS names for the certificate.
+   */
+  dnsNames?: InputArray<string>
+
+  /**
+   * The native data to pass to the implementation.
+   *
+   * This is used for data which implementation may natively understand
+   * and may use this data to create certificates using native resources.
+   */
+  nativeData?: unknown
+}
+
+export type TlsCertificateArgs = TlsCertificateSpec & {
+  /**
+   * The issuer to use for the certificate.
+   */
+  issuer?: Input<common.TlsIssuer>
+
+  /**
+   * The issuers to use for the certificate.
+   *
+   * If multiple issuers are provided, the certificate will be created using the first issuer that supports the requested common name.
+   */
+  issuers?: InputArray<common.TlsIssuer>
+}
+
+export class TlsCertificate extends ComponentResource {
+  /**
+   * The underlying resource created by the implementation.
+   */
+  readonly resource: Output<Resource>
+
+  constructor(name: string, args: TlsCertificateArgs, opts?: ComponentResourceOptions) {
+    super("highstate:common:TlsCertificate", name, args, opts)
+
+    const issuers = normalizeInputs(args.issuer, args.issuers)
+
+    this.resource = output({
+      issuers,
+      commonName: args.commonName,
+      dnsNames: args.dnsNames,
+    }).apply(async ({ issuers, commonName, dnsNames }) => {
+      // for now, we require single issuer to match all requested names
+      const matchedIssuer = issuers.find(issuer => {
+        if (commonName && !commonName.endsWith(issuer.domain)) {
+          return false
+        }
+
+        if (dnsNames && !dnsNames.every(name => name.endsWith(issuer.domain))) {
+          return false
+        }
+
+        return true
+      })
+
+      if (!matchedIssuer) {
+        throw new Error(
+          `No TLS issuer matched the common name "${commonName}" and DNS names "${dnsNames?.join(", ") ?? ""}"`,
+        )
+      }
+
+      return await tlsCertificateMediator.call(matchedIssuer.implRef, {
+        name,
+        spec: args,
+      })
+    })
+  }
+
+  private static readonly tlsCertificateCache = new Map<string, TlsCertificate>()
+
+  /**
+   * Creates a TLS certificate for the specified common name and DNS names.
+   *
+   * If a TLS certificate with the same name already exists, it will be reused.
+   *
+   * @param name The name of the TLS certificate.
+   * @param args The arguments for the TLS certificate.
+   * @param opts The options for the resource.
+   */
+  static createOnce(
+    name: string,
+    args: TlsCertificateArgs,
+    opts?: ComponentResourceOptions,
+  ): TlsCertificate {
+    return getOrCreate(
+      TlsCertificate.tlsCertificateCache,
+      name,
+      () => new TlsCertificate(name, args, opts),
+    )
+  }
+}

package/src/units/access-point/index.ts

@@ -0,0 +1,12 @@
+import { common } from "@highstate/library"
+import { forUnit } from "@highstate/pulumi"
+
+const { inputs, outputs } = forUnit(common.accessPoint)
+
+export default outputs({
+  accessPoint: {
+    gateway: inputs.gateway,
+    tlsIssuers: inputs.tlsIssuers ?? [],
+    dnsProviders: inputs.dnsProviders ?? [],
+  },
+})

package/src/units/databases/existing-mariadb/index.ts

@@ -0,0 +1,14 @@
+import { databases } from "@highstate/library"
+import { forUnit } from "@highstate/pulumi"
+import { parseEndpoints } from "../../../shared"
+
+const { args, secrets, inputs, outputs } = forUnit(databases.existingMariadb)
+
+export default outputs({
+  mariadb: {
+    endpoints: parseEndpoints(args.endpoints, inputs.endpoints),
+    username: args.username,
+    password: secrets.password,
+    database: args.database,
+  },
+})

package/src/units/databases/existing-mongodb/index.ts

@@ -0,0 +1,14 @@
+import { databases } from "@highstate/library"
+import { forUnit } from "@highstate/pulumi"
+import { parseEndpoints } from "../../../shared"
+
+const { args, secrets, inputs, outputs } = forUnit(databases.existingMongodb)
+
+export default outputs({
+  mongodb: {
+    endpoints: parseEndpoints(args.endpoints, inputs.endpoints),
+    username: args.username,
+    password: secrets.password,
+    database: args.database,
+  },
+})

package/src/units/databases/existing-postgresql/index.ts

@@ -0,0 +1,14 @@
+import { databases } from "@highstate/library"
+import { forUnit } from "@highstate/pulumi"
+import { parseEndpoints } from "../../../shared"
+
+const { args, secrets, inputs, outputs } = forUnit(databases.existingPostgresql)
+
+export default outputs({
+  postgresql: {
+    endpoints: parseEndpoints(args.endpoints, inputs.endpoints),
+    username: args.username,
+    password: secrets.password,
+    database: args.database,
+  },
+})