@takodotid/circuit 0.6.0 → 0.8.0

package/src/core/secrets.ts

@@ -1,18 +1,28 @@
-// Secrets are references in the config and values only at the moment a command is sent. A reference names a variable in the environment or `.env.local`, or a file kept out of the repository.
+// Secrets are references in the config and values only at the moment a command is sent. A reference names a variable, set in the environment or in `.env` beside the config, or a file kept out of the repository. A variable's value may itself be a 1Password reference, `op://vault/item/field`, read with the 1Password CLI.
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { Secret } from "../schema";
 
-let localFile: Record<string, string> | undefined;
+/** The directory of the config file. `.env` and secret files are found from here. */
+let root = process.cwd();
 
-/** `.env.local` in the working directory, read once. */
-function local(): Record<string, string> {
-    if (localFile) return localFile;
+let envFile: Record<string, string> | undefined;
+const fromOnePassword = new Map<string, string>();
 
-    localFile = {};
-    const path = join(process.cwd(), ".env.local");
-    if (!existsSync(path)) return localFile;
+/** Find `.env` and secret files from this directory, the config file's, instead of the working directory. */
+export function useRoot(directory: string): void {
+    root = directory;
+    envFile = undefined;
+}
+
+/** `.env` beside the config, read once. */
+function dotenv(): Record<string, string> {
+    if (envFile) return envFile;
+
+    envFile = {};
+    const path = join(root, ".env");
+    if (!existsSync(path)) return envFile;
 
     for (const line of readFileSync(path, "utf8").split("\n")) {
         const trimmed = line.trim();
@@ -21,23 +31,60 @@ function local(): Record<string, string> {
         const separator = trimmed.indexOf("=");
         if (separator <= 0) continue;
 
-        localFile[trimmed.slice(0, separator).trim()] = trimmed.slice(separator + 1).trim();
+        const value = trimmed.slice(separator + 1).trim();
+        const unquoted = /^(["']).*\1$/.test(value) ? value.slice(1, -1) : value;
+        envFile[trimmed.slice(0, separator).trim()] = unquoted;
     }
 
-    return localFile;
+    return envFile;
+}
+
+/** Read a 1Password reference with the 1Password CLI, `op`, once per run. */
+function readOnePassword(name: string, reference: string): string {
+    const cached = fromOnePassword.get(reference);
+    if (cached !== undefined) return cached;
+
+    let result: ReturnType<typeof Bun.spawnSync>;
+    try {
+        result = Bun.spawnSync(["op", "read", "--no-newline", reference], { stdout: "pipe", stderr: "pipe" });
+    } catch {
+        throw new Error(`secret ${name} is a 1Password reference, and the 1Password CLI, op, is not installed`);
+    }
+
+    if (result.exitCode !== 0) {
+        const reason = result.stderr?.toString().trim() || `op exited with ${result.exitCode}`;
+        throw new Error(`secret ${name}: 1Password could not read ${reference}: ${reason}`);
+    }
+
+    const value = result.stdout?.toString() ?? "";
+    fromOnePassword.set(reference, value);
+    return value;
 }
 
 export const isSecret = (value: unknown): value is Secret =>
     typeof value === "object" && value !== null && ("secret" in value || "secret_file" in value);
 
 /** How a reference is written inside a marker: a variable's name, or `file:` and a path. */
-const referenceOf = (secret: Secret) => ("secret" in secret ? secret.secret : `file:${secret.secret_file}`);
+export const referenceOf = (secret: Secret) => ("secret" in secret ? secret.secret : `file:${secret.secret_file}`);
+
+/** Where a reference's value comes from, such as `.env` or `1Password, through .env`, without reading it. Undefined when it is set nowhere. */
+export function sourceOf(reference: string): string | undefined {
+    if (reference.startsWith("file:")) return existsSync(join(root, reference.slice("file:".length))) ? "a file" : undefined;
+
+    const value = process.env[reference] || dotenv()[reference];
+    if (!value) return undefined;
+
+    // Bun loads `.env` into the environment when it starts in the same directory, so the same value in both came from `.env`.
+    const where = process.env[reference] && process.env[reference] !== dotenv()[reference] ? "the environment" : ".env";
+
+    return value.startsWith("op://") ? `1Password, through ${where}` : where;
+}
 
 /** The value behind a reference, as `referenceOf` writes it. */
 function valueOf(reference: string): string {
     if (reference.startsWith("file:")) {
         const path = reference.slice("file:".length);
-        const fullPath = join(process.cwd(), path);
+        const fullPath = join(root, path);
         if (!existsSync(fullPath)) throw new Error(`secret file ${path} does not exist`);
 
         const value = readFileSync(fullPath, "utf8").trimEnd();
@@ -46,10 +93,10 @@ function valueOf(reference: string): string {
         return value;
     }
 
-    const value = process.env[reference] ?? local()[reference];
-    if (!value) throw new Error(`secret ${reference} is not set in the environment or .env.local`);
+    const value = process.env[reference] || dotenv()[reference];
+    if (!value) throw new Error(`secret ${reference} is not set in the environment or in .env`);
 
-    return value;
+    return value.startsWith("op://") ? readOnePassword(reference, value) : value;
 }
 
 /** The value of a secret, or of a variable named directly. */

package/src/presets/index.ts

@@ -1,7 +1,7 @@
 // Building blocks most networks write the same way: address lists, edge filters, a BGP import sanity policy, checks, and helpers for checks of your own. Each returns plain config to place where it belongs, so nothing here applies itself.
 
 import { contains } from "../core/addr";
-import type { Check, Finding } from "../core/define";
+import type { Check, Community, Finding } from "../core/define";
 import type { AclRule, Device, FilterRule, PolicyRule, Prefix, TcpFlag } from "../schema";
 
 /** IPv4 sources that never arrive from the internet: loopback, link-local and "this network", after RFC 6890. */
@@ -107,22 +107,19 @@ export const exportsEndInReject: Check = (devices) => {
 export const vlansOf = (port: { access_vlan?: string; trunk_vlans?: readonly string[] }): string[] =>
     [port.access_vlan, ...(port.trunk_vlans ?? [])].filter((vlan): vlan is string => vlan !== undefined);
 
-/** Where traffic from outside, before anything filters it, may go. */
+/** Where traffic from outside, before anything filters it, may go. Every VLAN not listed as untrusted is trusted, so a VLAN added later is protected without being listed. */
 export type TrustBoundary = {
     /** VLANs carrying traffic straight from outside: transits, exchanges, an ISP handoff. */
     untrusted: readonly string[];
-    /** VLANs that must not meet them on a port: customers, servers, management. */
-    trusted: readonly string[];
-    /** The devices that filter: the only ones that may give an untrusted VLAN an address, and the only ones a port carrying both may face. */
+    /** The devices that filter: the only ones that may give an untrusted VLAN an address, and the only ones a port carrying both kinds may face. */
     routers: readonly string[];
 };
 
-/** A check: untrusted traffic reaches trusted VLANs only through a router. A port carrying both faces a router or is on one, and only a router gives an untrusted VLAN an address. */
+/** A check: traffic from outside reaches your own VLANs only through a router. A port or LAG carrying an untrusted VLAN beside any other is on a router or faces one, and only a router gives an untrusted VLAN an address. */
 export const trustBoundary =
     (boundary: TrustBoundary): Check =>
     (devices) => {
         const untrusted = new Set(boundary.untrusted);
-        const trusted = new Set(boundary.trusted);
         const routers = new Set(boundary.routers);
         const findings: Finding[] = [];
 
@@ -153,7 +150,7 @@ export const trustBoundary =
             ];
 
             for (const { what, carried, faces } of carriers) {
-                const mixes = carried.some((vlan) => untrusted.has(vlan)) && carried.some((vlan) => trusted.has(vlan));
+                const mixes = carried.some((vlan) => untrusted.has(vlan)) && carried.some((vlan) => !untrusted.has(vlan));
                 const facesRouter = isRouter || faces.some((name) => routers.has(name));
 
                 if (mixes && !facesRouter) {
@@ -209,3 +206,133 @@ export const tunnelsOutsideOffered: Check = (devices) => {
 
     return findings;
 };
+
+/**
+ * A BGP community scheme of large communities, `asn:function:parameter`, in the style of RFC 8195. Each field names the function number your network uses for it; leave out what your network does not offer.
+ */
+export type CommunityScheme<Class extends string = string> = {
+    /** Your AS. It is the first part of every community. */
+    asn: number;
+    /** Set on import: the kind of neighbor a route came from, `asn:function:class`. */
+    learned_from?: { function: number; classes: Readonly<Record<Class, number>> };
+    /** Set on import: the site a route was learned at, `asn:function:site`. `sites` names the sites, for the catalogue. */
+    learned_at?: { function: number; sites?: Readonly<Record<number, string>> };
+    /** Set on import: the AS a route was learned from, `asn:function:asn`. */
+    learned_from_as?: number;
+    /** Set by a customer: do not announce the route to an AS, `asn:function:asn`, or to anyone, `asn:function:0`. */
+    do_not_announce?: number;
+    /** Set by a customer: prepend toward an AS once, twice or three times, `asn:function:asn`. */
+    prepend?: { once?: number; twice?: number; three_times?: number };
+};
+
+const PREPENDS = [
+    ["once", 1],
+    ["twice", 2],
+    ["three_times", 3],
+] as const;
+
+const article = (word: string) => (/^[aeiou]/i.test(word) ? `an ${word}` : `a ${word}`);
+
+/**
+ * Policy rules and a catalogue from one community scheme, so the communities your routers set, the ones they act on, and the ones you publish never disagree.
+ *
+ * - `tag(neighborClass, neighborAs, { site, keepActions })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. `site` is needed when the scheme has `learned_at`. With `keepActions`, for a customer, its action communities stay.
+ * - `actions(neighborAs)`: rules for an export policy toward one neighbor. They act on a customer's action communities, then remove all of yours. Place them before the rules that accept.
+ * - `catalogue`: every community, for `communities` in `defineNetwork`.
+ */
+export function communityScheme<const Class extends string>(scheme: CommunityScheme<Class>) {
+    const { asn } = scheme;
+    const community = (fn: number, parameter: number | string) => `${asn}:${fn}:${parameter}`;
+    const ours = { standard: [`${asn}:*`], large: [`${asn}:*:*`] };
+
+    const information = [scheme.learned_from?.function, scheme.learned_at?.function, scheme.learned_from_as].filter(
+        (fn): fn is number => fn !== undefined
+    );
+
+    const tag = (
+        neighborClass: Class,
+        neighborAs: number,
+        options: { site?: number; keepActions?: boolean } = {}
+    ): PolicyRule<never, never> => {
+        const { site, keepActions = false } = options;
+        if (scheme.learned_at && site === undefined)
+            throw new Error(`communityScheme: tag for AS${neighborAs} needs a site, for learned_at`);
+
+        return {
+            description: `Learned from AS${neighborAs}`,
+            set: {
+                remove_communities: ours.standard,
+                remove_large_communities: keepActions ? information.map((fn) => community(fn, "*")) : ours.large,
+                add_large_communities: [
+                    ...(scheme.learned_from ? [community(scheme.learned_from.function, scheme.learned_from.classes[neighborClass])] : []),
+                    ...(scheme.learned_at ? [community(scheme.learned_at.function, site!)] : []),
+                    ...(scheme.learned_from_as !== undefined ? [community(scheme.learned_from_as, neighborAs)] : []),
+                ],
+            },
+        };
+    };
+
+    const actions = (neighborAs: number): PolicyRule<never, never>[] => [
+        ...(scheme.do_not_announce !== undefined
+            ? [
+                  {
+                      description: "Asked not to be announced anywhere",
+                      match: { large_community: community(scheme.do_not_announce, 0) },
+                      action: "reject" as const,
+                  },
+                  {
+                      description: `Asked not to be announced to AS${neighborAs}`,
+                      match: { large_community: community(scheme.do_not_announce, neighborAs) },
+                      action: "reject" as const,
+                  },
+              ]
+            : []),
+        ...PREPENDS.flatMap(([name, times]) => {
+            const fn = scheme.prepend?.[name];
+            if (fn === undefined) return [];
+
+            return [
+                {
+                    description: `Asked to prepend ${name.replace("_", " ")} to AS${neighborAs}`,
+                    match: { large_community: community(fn, neighborAs) },
+                    set: { prepend: times },
+                },
+            ];
+        }),
+        {
+            description: "Our communities stay inside our network",
+            set: { remove_communities: ours.standard, remove_large_communities: ours.large },
+        },
+    ];
+
+    const catalogue: Community[] = [
+        ...Object.entries<number>(scheme.learned_from?.classes ?? {}).map(([name, value]) => ({
+            community: community(scheme.learned_from!.function, value),
+            description: `Learned from ${article(name)}`,
+        })),
+        ...(scheme.learned_at
+            ? [
+                  ...Object.entries(scheme.learned_at.sites ?? {}).map(([site, name]) => ({
+                      community: community(scheme.learned_at!.function, site),
+                      description: `Learned in ${name}`,
+                  })),
+                  { community: community(scheme.learned_at.function, "nnn"), description: "Learned at site $0" },
+              ]
+            : []),
+        ...(scheme.learned_from_as !== undefined
+            ? [{ community: community(scheme.learned_from_as, "nnn"), description: "Learned from AS$0" }]
+            : []),
+        ...(scheme.do_not_announce !== undefined
+            ? [
+                  { community: community(scheme.do_not_announce, 0), description: "Do not announce to anyone" },
+                  { community: community(scheme.do_not_announce, "nnn"), description: "Do not announce to AS$0" },
+              ]
+            : []),
+        ...PREPENDS.flatMap(([name]) => {
+            const fn = scheme.prepend?.[name];
+            return fn === undefined ? [] : [{ community: community(fn, "nnn"), description: `Prepend ${name.replace("_", " ")} to AS$0` }];
+        }),
+    ];
+
+    return { community, tag, actions, catalogue };
+}

package/src/schema/common.ts

@@ -1,15 +1,15 @@
 /**
  * A value kept out of the repository and resolved only when a device is applied.
  *
- * `secret("NAME")` reads a variable from the environment or `.env.local`. `secretFile("path")` reads a file, relative to the project root, for a value that spans lines such as a private key in PEM. Keep that file out of git.
+ * `secret("NAME")` reads a variable from the environment or `.env` beside the config; a value written as `op://vault/item/field` is read from 1Password. `secretFile("path")` reads a file, relative to the config file, for a value that spans lines such as a private key in PEM. Keep that file out of git.
  */
 export type Secret =
     | {
-          /** Name of the value in the environment or in `.env.local`. */
+          /** Name of the value in the environment or in `.env`. */
           readonly secret: string;
       }
     | {
-          /** Path of a file holding the value, relative to the project root. */
+          /** Path of a file holding the value, relative to the config file. */
           readonly secret_file: string;
       };
 

package/src/schema/routing.ts

@@ -18,7 +18,9 @@ export type StaticRoute<I extends string, F extends string> = {
     description?: string;
 };
 
-/** Our side of the relationship, as RFC 9234 defines it. */
+/**
+ * What a BGP neighbor is to us, with the roles RFC 9234 defines: `provider`, a transit we buy from; `customer`, one we sell transit to; `peer`, one we exchange our own routes with; `rs`, an exchange's route server; `rs-client`, a network using our route server.
+ */
 export type BgpRole = "provider" | "customer" | "peer" | "rs" | "rs-client";
 
 /** Settings a BGP neighbor can state itself or take from its group. */
@@ -33,8 +35,8 @@ export type NeighborSettings<P extends string> = {
     import?: P;
     /** Policy for routes announced. Nothing is announced when absent. */
     export?: P;
-    /** Our role toward this neighbor, which lets both sides reject a leak. */
-    local_role?: BgpRole;
+    /** What the neighbor is to us, such as `provider` for a transit. Both sides then reject a route leak, after RFC 9234. */
+    role?: BgpRole;
     /** The neighbor is more than one hop away. */
     multihop?: boolean;
     /** TCP MD5 password shared with the neighbor. */

package/templates/colocation/checks.ts

@@ -0,0 +1,38 @@
+// Rules of your own. `circuit validate` runs them beside Circuit's own, and an error stops `diff` and `apply`.
+
+import type { Check, Finding } from "@takodotid/circuit";
+import { contains } from "@takodotid/circuit";
+import { exportsEndInReject, trustBoundary } from "@takodotid/circuit/presets";
+import { TENANTS } from "./tenants";
+
+export default [
+    // Nothing leaves by accident: every export ends by rejecting what it did not accept.
+    exportsEndInReject,
+
+    // Traffic from the transit and the exchange reaches the tenants only through the router, which filters it.
+    trustBoundary({ untrusted: ["transit", "ix"], routers: ["edge-01"] }),
+
+    // Tenants never share a name, a number or an address.
+    () => {
+        const findings: Finding[] = [];
+        const error = (message: string) => findings.push({ level: "error", message });
+
+        TENANTS.forEach((t, index) => {
+            for (const other of TENANTS.slice(index + 1)) {
+                if (other.name === t.name) error(`tenant ${t.name} is declared twice`);
+                if (other.number === t.number) error(`tenants ${t.name} and ${other.name} share number ${t.number}`);
+
+                for (const block of t.blocks) {
+                    const clash = other.blocks.find(({ prefix }) => contains(prefix, block.prefix) || contains(block.prefix, prefix));
+                    if (clash) error(`${block.prefix} of ${t.name} overlaps ${clash.prefix} of ${other.name}`);
+                }
+            }
+
+            for (const { prefix, gateway } of t.blocks) {
+                if (!contains(prefix, gateway)) error(`the gateway ${gateway} of ${t.name} is outside ${prefix}`);
+            }
+        });
+
+        return findings;
+    },
+] satisfies Check[];

package/templates/colocation/circuit.config.ts

@@ -0,0 +1,9 @@
+// The network: every device Circuit manages, your own checks, and what is published about the network.
+
+import { defineNetwork } from "@takodotid/circuit";
+import checks from "./checks";
+import edge from "./edge-01";
+import { ASN, communities } from "./routing";
+import tor from "./tor-01";
+
+export default defineNetwork({ devices: [edge, tor], checks, asn: ASN, communities: communities.catalogue });

package/templates/colocation/edge-01.ts

@@ -0,0 +1,131 @@
+// The edge router: BGP with an IP transit and an internet exchange, the gateway of every tenant, and the filter between them.
+
+import type { Prefix } from "@takodotid/circuit";
+import { defineDevice, merge, secret } from "@takodotid/circuit";
+import { antiSpoofing, badTcpFlags, bgpSanity, MARTIANS, PRIVATE_RANGES } from "@takodotid/circuit/presets";
+import { ASN, communities } from "./routing";
+import { edgeRules, gateways, internetVlanNames, internetVlans } from "./tenancy";
+import { TENANTS } from "./tenants";
+
+/** The address space this router announces. */
+const OURS = ["198.51.100.0/24", "2001:db8:100::/48"] as const satisfies readonly Prefix[];
+
+/** Where the router is managed from. */
+const MANAGEMENT = "10.0.0.0/24" satisfies Prefix;
+
+/** Sources that never arrive from the internet: our own space, and addresses that are not on the internet at all. */
+const SPOOFED = [OURS[0], ...MARTIANS, ...PRIVATE_RANGES];
+
+export default defineDevice({
+    name: "edge-01",
+    platform: "routeros",
+    model: "CCR2216-1G-12XS-2XQ",
+    connection: { host: "10.0.0.1", user: "operator" },
+    users: { operator: { role: "admin", password: secret("EDGE_01_PASSWORD") } },
+
+    system: { timezone: "Asia/Jakarta", ntp: { servers: ["pool.ntp.org"] } },
+    management: { allow: [MANAGEMENT], ssh: {} },
+
+    vlans: merge(
+        {
+            mgmt: { id: 99, description: "Management of the switches" },
+            transit: { id: 300, description: "IP transit from Example Transit, AS64501" },
+            ix: { id: 200, description: "Peering LAN of Example IX" },
+        },
+        internetVlans(TENANTS)
+    ),
+
+    ports: {
+        "1g-1": { description: "Management", addresses: ["10.0.0.1/24"] },
+        "25g-1": { description: "Example Transit", access_vlan: "transit", acl: "edge" },
+        "25g-2": { description: "Example IX", access_vlan: "ix", acl: "edge" },
+        "100g-1": {
+            description: "tor-01",
+            speed: "40g",
+            trunk_vlans: ["mgmt", ...internetVlanNames(TENANTS)],
+            link: { device: "tor-01", port: "40g-1" },
+        },
+    },
+
+    interfaces: merge(
+        {
+            mgmt: { type: "vlan", vlan: "mgmt", addresses: ["10.0.99.1/24"] },
+            transit: { type: "vlan", vlan: "transit", addresses: ["203.0.113.2/30"] },
+            ix: { type: "vlan", vlan: "ix", addresses: ["192.0.2.10/24", "2001:db8:ffff::10/64"] },
+        },
+        gateways(TENANTS)
+    ),
+
+    routing: {
+        router_id: "203.0.113.2",
+        // A route for each block we announce, so it is in the table even when nothing inside it is up.
+        static: OURS.map((prefix) => ({ prefix, blackhole: true, description: "Originate" })),
+        bgp: {
+            asn: ASN,
+            networks: [...OURS],
+            neighbors: {
+                "example-transit": {
+                    address: "203.0.113.1",
+                    remote_as: 64501,
+                    role: "provider",
+                    import: "TRANSIT-IN",
+                    export: "OUT",
+                    max_prefixes: 1_200_000,
+                },
+                "example-ix-rs-v4": {
+                    address: "192.0.2.1",
+                    remote_as: 64502,
+                    role: "rs",
+                    import: "IX-IN",
+                    export: "OUT",
+                    max_prefixes: 100_000,
+                },
+                "example-ix-rs-v6": {
+                    address: "2001:db8:ffff::1",
+                    remote_as: 64502,
+                    role: "rs",
+                    import: "IX-IN",
+                    export: "OUT",
+                    max_prefixes: 50_000,
+                },
+            },
+        },
+    },
+
+    policies: {
+        SANITY: bgpSanity(),
+        // A route from the exchange is preferred over the same route from the transit: higher local preference wins.
+        "TRANSIT-IN": [{ call: "SANITY" }, communities.tag("transit", 64501), { set: { local_pref: 100 } }, { action: "accept" }],
+        "IX-IN": [{ call: "SANITY" }, communities.tag("exchange", 64502), { set: { local_pref: 200 } }, { action: "accept" }],
+        OUT: [
+            ...OURS.map((prefix) => ({ description: `Announce ${prefix}`, match: { prefix }, action: "accept" as const })),
+            { description: "Nothing else leaves", action: "reject" },
+        ],
+    },
+
+    firewall: {
+        address_sets: { "bgp-neighbors": ["203.0.113.1", "192.0.2.1", "2001:db8:ffff::1"] },
+        filter: {
+            input: {
+                default: "drop",
+                rules: [
+                    { description: "Replies", match: { state: ["established", "related"] }, action: "accept" },
+                    { description: "Ping", match: { protocol: "icmp" }, action: "accept" },
+                    { description: "Management", match: { src: MANAGEMENT }, action: "accept" },
+                    { description: "BGP", match: { protocol: "tcp", dst_port: 179, src_set: "bgp-neighbors" }, action: "accept" },
+                ],
+            },
+            forward: { rules: [...badTcpFlags()] },
+        },
+    },
+
+    // In the switch chip, before a packet reaches the router's CPU: spoofed sources first, then each tenant's own rules.
+    acls: {
+        edge: [
+            ...antiSpoofing("transit", SPOOFED),
+            ...antiSpoofing("ix", SPOOFED),
+            ...edgeRules(TENANTS, "transit"),
+            ...edgeRules(TENANTS, "ix"),
+        ],
+    },
+});

package/templates/colocation/routing.ts

@@ -0,0 +1,13 @@
+// What your network is on the internet: its AS number and its BGP communities.
+
+import { communityScheme } from "@takodotid/circuit/presets";
+
+/** Your AS number. */
+export const ASN = 64500;
+
+/** What your BGP communities mean. The router tags each route it learns with them, and `circuit communities` publishes them. */
+export const communities = communityScheme({
+    asn: ASN,
+    learned_from: { function: 1, classes: { transit: 1, exchange: 2 } },
+    learned_from_as: 3,
+});

package/templates/colocation/tenancy.ts

@@ -0,0 +1,97 @@
+// What a tenant is, and what each device carries for it. A tenant's file says what is the tenant's own; its VLANs and names follow from its name and number.
+
+import type { AclRule, Interface, IP, Port, Prefix, Vlan } from "@takodotid/circuit";
+import { familyOf } from "@takodotid/circuit";
+
+/** A tenant's networks. `internet` carries its servers' public addresses and reaches the router. `private` connects its own servers to each other and stays on the switches. */
+type TenantNetwork = "internet" | "private";
+
+export type Tenant<N extends string = string> = {
+    /** Lowercase, and never reused. Names everything the tenant has. */
+    name: N;
+    /** A number no other tenant has. Its internet VLAN is 1000 + number, its private VLAN 2000 + number. */
+    number: number;
+    /** Public blocks routed to the tenant. `gateway` is the router's address inside the block, which the tenant's servers use as their gateway. */
+    blocks: readonly { prefix: Prefix; gateway: IP }[];
+    /** Rules for traffic toward the tenant's IPv4 blocks from the transit and the exchange, such as a cap on UDP. Everything reaches the tenant when absent. */
+    acl?: readonly (Omit<AclRule<never>, "match"> & { match?: Omit<NonNullable<AclRule<never>["match"]>, "vlan" | "dst"> })[];
+    /** The tenant's ports, by switch, then by port. A port in `private` gives the tenant a private network on that switch. */
+    ports: Readonly<
+        Record<string, Readonly<Record<string, { description: string; access?: TenantNetwork; trunk?: readonly TenantNetwork[] }>>>
+    >;
+};
+
+/** Declare a tenant. */
+export const tenant = <const N extends string>(spec: Tenant<N>): Tenant<N> => spec;
+
+const internetVlan = <N extends string>(t: Tenant<N>) => `${t.name}-internet` as const;
+const privateVlan = <N extends string>(t: Tenant<N>) => `${t.name}-private` as const;
+
+/** Every tenant's internet VLAN. The router has them all, and so does each switch, to carry them up to the router. */
+export const internetVlans = <N extends string>(tenants: readonly Tenant<N>[]) =>
+    Object.fromEntries(tenants.map((t) => [internetVlan(t), { id: 1000 + t.number, description: `Tenant ${t.name} internet` }])) as Record<
+        `${N}-internet`,
+        Vlan
+    >;
+
+/** The names of every tenant's internet VLAN, for a trunk toward the router. */
+export const internetVlanNames = <N extends string>(tenants: readonly Tenant<N>[]) => tenants.map(internetVlan);
+
+/** The private VLANs one switch has: those of tenants with a port on it in their private network. */
+export const privateVlans = <N extends string>(tenants: readonly Tenant<N>[], device: string) =>
+    Object.fromEntries(
+        tenants
+            .filter((t) =>
+                Object.values(t.ports[device] ?? {}).some((port) => port.access === "private" || port.trunk?.includes("private"))
+            )
+            .map((t) => [privateVlan(t), { id: 2000 + t.number, description: `Tenant ${t.name} private` }])
+    ) as Record<`${N}-private`, Vlan>;
+
+/** The tenants' ports on one switch. */
+export function portsOn<N extends string>(tenants: readonly Tenant<N>[], device: string) {
+    const ports: Record<string, Port<`${N}-internet` | `${N}-private`, string, string, string>> = {};
+
+    for (const t of tenants) {
+        const vlanOf = (network: TenantNetwork) => (network === "internet" ? internetVlan(t) : privateVlan(t));
+
+        for (const [name, { access, trunk, description }] of Object.entries(t.ports[device] ?? {})) {
+            ports[name] = {
+                description,
+                ...(access ? { access_vlan: vlanOf(access) } : {}),
+                ...(trunk ? { trunk_vlans: trunk.map(vlanOf) } : {}),
+            };
+        }
+    }
+
+    return ports;
+}
+
+/** The router's interface on each tenant's internet VLAN, holding the tenant's gateways. */
+export function gateways<N extends string>(tenants: readonly Tenant<N>[]) {
+    const interfaces = {} as Record<`${N}-internet`, Interface<`${N}-internet`, never>>;
+
+    for (const t of tenants) {
+        interfaces[internetVlan(t)] = {
+            type: "vlan",
+            vlan: internetVlan(t),
+            description: `Tenant ${t.name}`,
+            addresses: t.blocks.map(({ prefix, gateway }) => `${gateway}/${prefix.split("/")[1]}`),
+        };
+    }
+
+    return interfaces;
+}
+
+/** Each tenant's `acl` rules on one VLAN from outside, one per rule and IPv4 block, each limited to traffic toward that block. */
+export const edgeRules = <V extends string>(tenants: readonly Tenant[], vlan: V): AclRule<V>[] =>
+    tenants.flatMap((t) =>
+        (t.acl ?? []).flatMap((rule) =>
+            t.blocks
+                .filter(({ prefix }) => familyOf(prefix) === "ipv4")
+                .map(({ prefix }) => ({
+                    ...rule,
+                    ...(rule.description ? { description: `${vlan}: ${rule.description}` } : {}),
+                    match: { ...rule.match, vlan, dst: prefix },
+                }))
+        )
+    );

package/templates/colocation/tenants/acme.ts

@@ -0,0 +1,19 @@
+// An example tenant. Copy this file for each new tenant, and add it to index.ts.
+
+import { tenant } from "../tenancy";
+
+export default tenant({
+    name: "acme",
+    number: 1,
+    blocks: [
+        { prefix: "198.51.100.8/29", gateway: "198.51.100.9" },
+        { prefix: "2001:db8:100:1::/64", gateway: "2001:db8:100:1::1" },
+    ],
+    acl: [{ description: "UDP to acme above 1G", match: { protocol: "udp" }, action: "accept", rate: "1G" }],
+    ports: {
+        "tor-01": {
+            "10g-1": { description: "acme server 1", trunk: ["internet", "private"] },
+            "10g-2": { description: "acme server 2", trunk: ["internet", "private"] },
+        },
+    },
+});

package/templates/colocation/tenants/index.ts

@@ -0,0 +1,5 @@
+// Every tenant. A tenant joins by being added here, and leaves by being removed: the next apply takes away everything it had.
+
+import acme from "./acme";
+
+export const TENANTS = [acme] as const;