Skip to main content Link Search Menu Expand Document (external link)
the-wireguard-effect

WireguardGenerate overview

Tools to help generate wireguard configs for common situations.

Added in v1.0.0

Table of contents

AllowedIPs Transformers

addAllowedIPs

Adds an allowed IP to a node in the network.

Signature

export declare const addAllowedIPs: (<
  Nodes extends
    | readonly [node1: WireguardIPv4Node, node2: WireguardIPv4Node, ...rest: WireguardIPv4Node[]]
    | readonly [node1: WireguardIPv6Node, node2: WireguardIPv6Node, ...rest: WireguardIPv6Node[]]
>(
  nodeToIp: Extract<Nodes[number], WireguardRoamingPeer>["ip"] | Extract<Nodes[number], WireguardServer>[1]["ip"],
  nodeFromIp: Extract<Nodes[number], WireguardRoamingPeer>["ip"] | Extract<Nodes[number], WireguardServer>[1]["ip"],
  cidrs: readonly [
    `${string}/${number}` | InternetSchemas.IPv4CidrBlock | InternetSchemas.IPv6CidrBlock,
    ...(`${string}/${number}` | InternetSchemas.IPv4CidrBlock | InternetSchemas.IPv6CidrBlock)[]
  ]
) => (allowedIPsLayer: AllowedIPsLayer<Nodes>) => AllowedIPsLayer<Nodes>) &
  (<
    Nodes extends
      | readonly [node1: WireguardIPv4Node, node2: WireguardIPv4Node, ...rest: WireguardIPv4Node[]]
      | readonly [node1: WireguardIPv6Node, node2: WireguardIPv6Node, ...rest: WireguardIPv6Node[]]
  >(
    allowedIPsLayer: AllowedIPsLayer<Nodes>,
    nodeToIp: Extract<Nodes[number], WireguardRoamingPeer>["ip"] | Extract<Nodes[number], WireguardServer>[1]["ip"],
    nodeFromIp: Extract<Nodes[number], WireguardRoamingPeer>["ip"] | Extract<Nodes[number], WireguardServer>[1]["ip"],
    cidrs: readonly [
      `${string}/${number}` | InternetSchemas.IPv4CidrBlock | InternetSchemas.IPv6CidrBlock,
      ...(`${string}/${number}` | InternetSchemas.IPv4CidrBlock | InternetSchemas.IPv6CidrBlock)[]
    ]
  ) => AllowedIPsLayer<Nodes>)

Added in v1.0.0

computeAllowedIPsFromConnections

Generates the allowed IPs for each node in the network based on the connections is has to the other nodes.

Signature

export declare const computeAllowedIPsFromConnections: <
  Nodes extends
    | readonly [node1: WireguardIPv4Node, node2: WireguardIPv4Node, ...rest: WireguardIPv4Node[]]
    | readonly [node1: WireguardIPv6Node, node2: WireguardIPv6Node, ...rest: WireguardIPv6Node[]]
>(
  connectionsLayer: ConnectionsLayer<Nodes>
) => AllowedIPsLayer<Nodes>

Added in v1.0.0

Connection Transformers

addConnection

Adds a direct connection between two nodes in the network.

Signature

export declare const addConnection: (<
  Nodes extends
    | readonly [node1: WireguardIPv4Node, node2: WireguardIPv4Node, ...rest: WireguardIPv4Node[]]
    | readonly [node1: WireguardIPv6Node, node2: WireguardIPv6Node, ...rest: WireguardIPv6Node[]]
>(
  from: Extract<Nodes[number], WireguardRoamingPeer>["ip"] | Extract<Nodes[number], WireguardServer>[1]["ip"],
  to: Extract<Nodes[number], WireguardRoamingPeer>["ip"] | Extract<Nodes[number], WireguardServer>[1]["ip"]
) => (connectionsLayer: ConnectionsLayer<Nodes>) => ConnectionsLayer<Nodes>) &
  (<
    Nodes extends
      | readonly [node1: WireguardIPv4Node, node2: WireguardIPv4Node, ...rest: WireguardIPv4Node[]]
      | readonly [node1: WireguardIPv6Node, node2: WireguardIPv6Node, ...rest: WireguardIPv6Node[]]
  >(
    connectionsLayer: ConnectionsLayer<Nodes>,
    from: Extract<Nodes[number], WireguardRoamingPeer>["ip"] | Extract<Nodes[number], WireguardServer>[1]["ip"],
    to: Extract<Nodes[number], WireguardRoamingPeer>["ip"] | Extract<Nodes[number], WireguardServer>[1]["ip"]
  ) => ConnectionsLayer<Nodes>)

Added in v1.0.0

generateHubAndSpokeConnections

Generates connections in a hub and spoke pattern for all nodes in the network.

Signature

export declare const generateHubAndSpokeConnections: <
  Nodes extends
    | readonly [node1: WireguardIPv4Node, node2: WireguardIPv4Node, ...rest: WireguardIPv4Node[]]
    | readonly [node1: WireguardIPv6Node, node2: WireguardIPv6Node, ...rest: WireguardIPv6Node[]]
>(
  keysLayer: keysLayer<Nodes>
) => ConnectionsLayer<Nodes>

Added in v1.0.0

generateStarConnections

Generates connections in a star pattern for all nodes in the network.

Signature

export declare const generateStarConnections: <
  Nodes extends
    | readonly [node1: WireguardIPv4Node, node2: WireguardIPv4Node, ...rest: WireguardIPv4Node[]]
    | readonly [node1: WireguardIPv6Node, node2: WireguardIPv6Node, ...rest: WireguardIPv6Node[]]
>(
  keysLayer: keysLayer<Nodes>
) => ConnectionsLayer<Nodes>

Added in v1.0.0

Generator

toConfigs

Converts a network into configs.

Signature

export declare const toConfigs: <
  Nodes extends
    | readonly [node1: WireguardIPv4Node, node2: WireguardIPv4Node, ...rest: WireguardIPv4Node[]]
    | readonly [node1: WireguardIPv6Node, node2: WireguardIPv6Node, ...rest: WireguardIPv6Node[]]
>({
  allowedIPs,
  connections,
  keys,
  nodes,
  wireguardNetworkCidr
}: WireguardNetwork<Nodes>) => Effect.Effect<
  readonly [
    WireguardConfig.WireguardConfig,
    WireguardConfig.WireguardConfig,
    ...ReadonlyArray<WireguardConfig.WireguardConfig>
  ],
  ParseResult.ParseError | WireguardErrors.WireguardError,
  never
>

Added in v1.0.0

Generators

generateLanHubAndSpokeAccess

Builds on “Server hub and spoke access”, allowing you to access your entire LAN as well.

Signature

export declare const generateLanHubAndSpokeAccess: <
  Nodes extends
    | readonly [server: WireguardIPv4Server, WireguardIPv4Node, ...WireguardIPv4Node[]]
    | readonly [server: WireguardIPv6Server, WireguardIPv6Node, ...WireguardIPv6Node[]],
  NetworkCidr extends Nodes[0] extends WireguardIPv4Node
    ? InternetSchemas.IPv4CidrBlock
    : Nodes[0] extends WireguardIPv6Node
      ? InternetSchemas.IPv6CidrBlock
      : never,
  NetworkCidr2 extends Nodes[0] extends WireguardIPv4Server
    ? InternetSchemas.IPv4CidrBlock | [InternetSchemas.IPv4CidrBlock, ...InternetSchemas.IPv4CidrBlock[]]
    : Nodes[0] extends WireguardIPv6Server
      ? InternetSchemas.IPv6CidrBlock | [InternetSchemas.IPv6CidrBlock, ...InternetSchemas.IPv6CidrBlock[]]
      : never
>(options: {
  nodes: Nodes
  lanNetworkCidr: NetworkCidr2
  wireguardNetworkCidr: NetworkCidr
}) => WireguardNetwork<Nodes>

Added in v1.0.0

generateLanToLanAccess

Builds on “Server to server access”, allowing two entire networks to communicate.

Signature

export declare const generateLanToLanAccess: <
  Nodes extends
    | readonly [server1: WireguardIPv4Server, server2: WireguardIPv4Server]
    | readonly [server1: WireguardIPv6Server, server2: WireguardIPv6Server],
  NetworkCidr1 extends Nodes[0] extends WireguardIPv4Node
    ? InternetSchemas.IPv4CidrBlock
    : Nodes[0] extends WireguardIPv6Node
      ? InternetSchemas.IPv6CidrBlock
      : never,
  NetworkCidr2 extends Nodes[0] extends WireguardIPv4Server
    ? InternetSchemas.IPv4CidrBlock | [InternetSchemas.IPv4CidrBlock, ...InternetSchemas.IPv4CidrBlock[]]
    : Nodes[0] extends WireguardIPv6Server
      ? InternetSchemas.IPv6CidrBlock | [InternetSchemas.IPv6CidrBlock, ...InternetSchemas.IPv6CidrBlock[]]
      : never,
  NetworkCidr3 extends Nodes[1] extends WireguardIPv4Server
    ? InternetSchemas.IPv4CidrBlock | [InternetSchemas.IPv4CidrBlock, ...InternetSchemas.IPv4CidrBlock[]]
    : Nodes[1] extends WireguardIPv6Server
      ? InternetSchemas.IPv6CidrBlock | [InternetSchemas.IPv6CidrBlock, ...InternetSchemas.IPv6CidrBlock[]]
      : never
>(options: {
  nodes: Nodes
  server1Lan: NetworkCidr2
  server2Lan: NetworkCidr3
  wireguardNetworkCidr: NetworkCidr1
}) => WireguardNetwork<Nodes>

Added in v1.0.0

generateRemoteAccessToLan

Builds on “Remote access to server”, allowing you to access your entire LAN as well.

Signature

export declare const generateRemoteAccessToLan: <
  Nodes extends
    | readonly [server: WireguardIPv4Server, client: WireguardIPv4Node]
    | readonly [server: WireguardIPv6Server, client: WireguardIPv6Node],
  NetworkCidr1 extends Nodes[0] extends WireguardIPv4Node
    ? InternetSchemas.IPv4CidrBlock
    : Nodes[0] extends WireguardIPv6Node
      ? InternetSchemas.IPv6CidrBlock
      : never,
  NetworkCidr2 extends Nodes[0] extends WireguardIPv4Server
    ? InternetSchemas.IPv4CidrBlock | [InternetSchemas.IPv4CidrBlock, ...InternetSchemas.IPv4CidrBlock[]]
    : Nodes[0] extends WireguardIPv6Server
      ? InternetSchemas.IPv6CidrBlock | [InternetSchemas.IPv6CidrBlock, ...InternetSchemas.IPv6CidrBlock[]]
      : never
>(options: {
  nodes: Nodes
  wireguardNetworkCidr: NetworkCidr1
  lanNetworkCidr: NetworkCidr2
}) => WireguardNetwork<Nodes>

Added in v1.0.0

generateRemoteAccessToServer

Use your phone or computer to remotely access just the wireguard server.

Signature

export declare const generateRemoteAccessToServer: <
  Nodes extends
    | readonly [server: WireguardIPv4Server, client: WireguardIPv4Node]
    | readonly [server: WireguardIPv6Server, client: WireguardIPv6Node],
  NetworkCidr extends Nodes[0] extends WireguardIPv4Node
    ? InternetSchemas.IPv4CidrBlock
    : Nodes[0] extends WireguardIPv6Node
      ? InternetSchemas.IPv6CidrBlock
      : never
>(options: {
  nodes: Nodes
  wireguardNetworkCidr: NetworkCidr
}) => WireguardNetwork<Nodes>

Added in v1.0.0

generateRemoteTunneledAccess

Securely access the Internet from untrusted networks by routing all of your traffic through the VPN and out the server’s internet connection.

Signature

export declare const generateRemoteTunneledAccess: <
  Nodes extends
    | readonly [server: WireguardIPv4Server, client: WireguardIPv4Node]
    | readonly [server: WireguardIPv6Server, client: WireguardIPv6Node],
  NetworkCidr1 extends Nodes[0] extends WireguardIPv4Node
    ? InternetSchemas.IPv4CidrBlock
    : Nodes[0] extends WireguardIPv6Node
      ? InternetSchemas.IPv6CidrBlock
      : never,
  NetworkCidr2 extends Nodes[0] extends WireguardIPv4Server
    ? InternetSchemas.IPv4CidrBlock | [InternetSchemas.IPv4CidrBlock, ...InternetSchemas.IPv4CidrBlock[]]
    : Nodes[0] extends WireguardIPv6Server
      ? InternetSchemas.IPv6CidrBlock | [InternetSchemas.IPv6CidrBlock, ...InternetSchemas.IPv6CidrBlock[]]
      : never
>(options: {
  nodes: Nodes
  lanNetworkCidr: NetworkCidr2
  wireguardNetworkCidr: NetworkCidr1
}) => WireguardNetwork<Nodes>

Added in v1.0.0

generateServerHubAndSpokeAccess

Builds on “Remote access to server”, except that all of the VPN clients can connect to each other as well. Note: all traffic between nodes must pass through the server.

Signature

export declare const generateServerHubAndSpokeAccess: <
  Nodes extends
    | readonly [server: WireguardIPv4Server, WireguardIPv4Node, ...WireguardIPv4Node[]]
    | readonly [server: WireguardIPv6Server, WireguardIPv6Node, ...WireguardIPv6Node[]],
  NetworkCidr extends Nodes[0] extends WireguardIPv4Node
    ? InternetSchemas.IPv4CidrBlock
    : Nodes[0] extends WireguardIPv6Node
      ? InternetSchemas.IPv6CidrBlock
      : never
>(options: {
  nodes: Nodes
  wireguardNetworkCidr: NetworkCidr
}) => WireguardNetwork<Nodes>

Added in v1.0.0

generateServerToServerAccess

Allows two servers to connect to each other.

Signature

export declare const generateServerToServerAccess: <
  Nodes extends
    | readonly [server1: WireguardIPv4Server, server2: WireguardIPv4Server]
    | readonly [server1: WireguardIPv6Server, server2: WireguardIPv6Server],
  NetworkCidr extends Nodes[0] extends WireguardIPv4Node
    ? InternetSchemas.IPv4CidrBlock
    : Nodes[0] extends WireguardIPv6Node
      ? InternetSchemas.IPv6CidrBlock
      : never
>(options: {
  nodes: Nodes
  wireguardNetworkCidr: NetworkCidr
}) => WireguardNetwork<Nodes>

Added in v1.0.0

generateVpnTunneledAccess

Route specific traffic through a commercial WireGuard VPN provider.

Signature

export declare const generateVpnTunneledAccess: <
  Nodes extends
    | readonly [server: WireguardIPv4Server, client: WireguardIPv4Node]
    | readonly [server: WireguardIPv6Server, client: WireguardIPv6Node],
  NetworkCidr extends Nodes[0] extends WireguardIPv4Node
    ? InternetSchemas.IPv4CidrBlock
    : Nodes[0] extends WireguardIPv6Node
      ? InternetSchemas.IPv6CidrBlock
      : never
>(options: {
  nodes: Nodes
  wireguardNetworkCidr: NetworkCidr
}) => WireguardNetwork<Nodes>

Added in v1.0.0

Key Transformers

addPreshareKeys

Generates preshare keys for all nodes in the network.

Signature

export declare const addPreshareKeys: <
  Nodes extends
    | readonly [node1: WireguardIPv4Node, node2: WireguardIPv4Node, ...rest: WireguardIPv4Node[]]
    | readonly [node1: WireguardIPv6Node, node2: WireguardIPv6Node, ...rest: WireguardIPv6Node[]]
>(
  keysLayer: keysLayer<Nodes>
) => keysLayer<Nodes>

Added in v1.0.0

generateKeys

Generates private+public keys for all nodes in the network.

Signature

export declare const generateKeys: <
  Nodes extends
    | readonly [node1: WireguardIPv4Node, node2: WireguardIPv4Node, ...rest: WireguardIPv4Node[]]
    | readonly [node1: WireguardIPv6Node, node2: WireguardIPv6Node, ...rest: WireguardIPv6Node[]]
>(
  nodesLayer: NodesLayer<Nodes>
) => keysLayer<Nodes>

Added in v1.0.0

WireguardGenerate

AllowedIPsLayer (type alias)

Layer containing the allowed IPs for each node in the network.

Signature

export type AllowedIPsLayer<
  Nodes extends
    | readonly [node1: WireguardIPv4Node, node2: WireguardIPv4Node, ...rest: Array<WireguardIPv4Node>]
    | readonly [node1: WireguardIPv6Node, node2: WireguardIPv6Node, ...rest: Array<WireguardIPv6Node>]
> = ConnectionsLayer<Nodes> & {
  allowedIPs: Record.ReadonlyRecord<
    Extract<Nodes[number], WireguardRoamingPeer>["ip"] | Extract<Nodes[number], WireguardServer>[1]["ip"],
    Array.NonEmptyReadonlyArray<{
      block: InternetSchemas.CidrBlockFromStringEncoded
      from: Extract<Nodes[number], WireguardRoamingPeer>["ip"] | Extract<Nodes[number], WireguardServer>[1]["ip"]
    }>
  >
}

Added in v1.0.0

ConnectionsLayer (type alias)

Layer containing the connections for each node in the network.

Signature

export type ConnectionsLayer<
  Nodes extends
    | readonly [node1: WireguardIPv4Node, node2: WireguardIPv4Node, ...rest: Array<WireguardIPv4Node>]
    | readonly [node1: WireguardIPv6Node, node2: WireguardIPv6Node, ...rest: Array<WireguardIPv6Node>]
> = keysLayer<Nodes> & {
  connections: Record.ReadonlyRecord<
    Extract<Nodes[number], WireguardRoamingPeer>["ip"] | Extract<Nodes[number], WireguardServer>[1]["ip"],
    Array.NonEmptyReadonlyArray<
      Extract<Nodes[number], WireguardRoamingPeer>["ip"] | Extract<Nodes[number], WireguardServer>[1]["ip"]
    >
  >
}

Added in v1.0.0

NodesLayer (type alias)

Base layer containing just the nodes in the network.

Signature

export type NodesLayer<
  Nodes extends
    | readonly [node1: WireguardIPv4Node, node2: WireguardIPv4Node, ...rest: Array<WireguardIPv4Node>]
    | readonly [node1: WireguardIPv6Node, node2: WireguardIPv6Node, ...rest: Array<WireguardIPv6Node>]
> = {
  nodes: Nodes
  wireguardNetworkCidr: Nodes[0] extends WireguardIPv4Node
    ? InternetSchemas.IPv4CidrBlock
    : Nodes[0] extends WireguardIPv6Node
      ? InternetSchemas.IPv6CidrBlock
      : never
}

Added in v1.0.0

WireguardNetwork (type alias)

The final network type.

Signature

export type WireguardNetwork<
  Nodes extends
    | readonly [node1: WireguardIPv4Node, node2: WireguardIPv4Node, ...rest: Array<WireguardIPv4Node>]
    | readonly [node1: WireguardIPv6Node, node2: WireguardIPv6Node, ...rest: Array<WireguardIPv6Node>]
> = AllowedIPsLayer<Nodes>

Added in v1.0.0

keysLayer (type alias)

Layer containing the keys for each node in the network.

Signature

export type keysLayer<
  Nodes extends
    | readonly [node1: WireguardIPv4Node, node2: WireguardIPv4Node, ...rest: Array<WireguardIPv4Node>]
    | readonly [node1: WireguardIPv6Node, node2: WireguardIPv6Node, ...rest: Array<WireguardIPv6Node>]
> = NodesLayer<Nodes> & {
  keys: Record.ReadonlyRecord<
    Extract<Nodes[number], WireguardRoamingPeer>["ip"] | Extract<Nodes[number], WireguardServer>[1]["ip"],
    Keys
  >
}

Added in v1.0.0