@takodotid/circuit 0.6.0 → 0.7.0

package/templates/colocation/tor-01.ts

@@ -0,0 +1,33 @@
+// The top-of-rack switch: the tenants' servers, and one uplink to the router.
+
+import { defineDevice, merge, secret } from "@takodotid/circuit";
+import { internetVlanNames, internetVlans, portsOn, privateVlans } from "./tenancy";
+import { TENANTS } from "./tenants";
+
+export default defineDevice({
+    name: "tor-01",
+    platform: "vrp",
+    model: "CE6855-48S6Q-HI",
+    connection: { host: "10.0.99.2", user: "operator" },
+    users: { operator: { role: "admin", password: secret("TOR_01_PASSWORD") } },
+
+    system: { timezone: "Asia/Jakarta", ntp: { servers: ["10.0.99.1"] } },
+    management: { allow: ["10.0.0.0/24"], ssh: {} },
+
+    lldp: true,
+    stp: {},
+
+    vlans: merge({ mgmt: { id: 99, description: "Management" } }, internetVlans(TENANTS), privateVlans(TENANTS, "tor-01")),
+
+    // Every tenant's ports, from its file in tenants/, beside the switch's own.
+    ports: merge(portsOn(TENANTS, "tor-01"), {
+        "40g-1": {
+            description: "edge-01",
+            trunk_vlans: ["mgmt", ...internetVlanNames(TENANTS)],
+            link: { device: "edge-01", port: "100g-1" },
+        },
+    }),
+
+    interfaces: { mgmt: { type: "vlan", vlan: "mgmt", addresses: ["10.0.99.2/24"] } },
+    routing: { static: [{ prefix: "0.0.0.0/0", via: "10.0.99.1" }] },
+});

package/templates/edge-router/checks.ts

@@ -0,0 +1,20 @@
+// Rules of your own. `circuit validate` runs them beside Circuit's own, and an error stops `diff` and `apply`.
+
+import type { Check } from "@takodotid/circuit";
+import { exportsEndInReject, neighborPolicies, trustBoundary } from "@takodotid/circuit/presets";
+
+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 rest of the network only through the router.
+    trustBoundary({ untrusted: ["transit", "ix"], routers: ["edge-01"] }),
+
+    // Every BGP session filters what it takes in.
+    (devices) =>
+        devices.flatMap((device) =>
+            neighborPolicies(device)
+                .filter((neighbor) => !neighbor.import)
+                .map((neighbor) => ({ level: "error" as const, device: device.name, message: `${neighbor.name} has no import policy` }))
+        ),
+] satisfies Check[];

package/templates/edge-router/circuit.config.ts

@@ -0,0 +1,8 @@
+// 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";
+
+export default defineNetwork({ devices: [edge], checks, asn: ASN, communities: communities.catalogue });

package/templates/edge-router/edge-01.ts

@@ -0,0 +1,108 @@
+// The edge router: BGP with an IP transit and an internet exchange, filtered on the way in and on the way out.
+
+import type { Prefix } from "@takodotid/circuit";
+import { defineDevice, secret } from "@takodotid/circuit";
+import { antiSpoofing, badTcpFlags, bgpSanity, MARTIANS, PRIVATE_RANGES } from "@takodotid/circuit/presets";
+import { ASN, communities } from "./routing";
+
+/** 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: {
+        transit: { id: 300, description: "IP transit from Example Transit, AS64501" },
+        ix: { id: 200, description: "Peering LAN of Example IX" },
+    },
+
+    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" },
+    },
+
+    interfaces: {
+        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"] },
+    },
+
+    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,
+                    local_role: "customer",
+                    import: "TRANSIT-IN",
+                    export: "OUT",
+                    max_prefixes: 1_200_000,
+                },
+                "example-ix-rs-v4": {
+                    address: "192.0.2.1",
+                    remote_as: 64502,
+                    local_role: "rs-client",
+                    import: "IX-IN",
+                    export: "OUT",
+                    max_prefixes: 100_000,
+                },
+                "example-ix-rs-v6": {
+                    address: "2001:db8:ffff::1",
+                    remote_as: 64502,
+                    local_role: "rs-client",
+                    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.
+    acls: { edge: [...antiSpoofing("transit", SPOOFED), ...antiSpoofing("ix", SPOOFED)] },
+});

package/templates/edge-router/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/project/AGENTS.md

@@ -0,0 +1,44 @@
+# AGENTS.md
+
+This repository describes a computer network with [Circuit](https://circuit.tako.id). Each network device, such as a router or a switch, has a TypeScript file that says how it should be configured. Circuit compares that file with what the device runs, and changes the device to match.
+
+You are helping the owner of this network. Changes you make here can take a network down, so work carefully and let the owner decide.
+
+## How Circuit works
+
+1. `circuit.config.ts` lists every device and the checks to run.
+2. Each device file calls `defineDevice`. What the file says is everything the device runs: a port, a user or a service that the file does not mention is removed or turned off when the device is applied.
+3. A field is only written when it has a value. There is no `enabled: false`; leave a field out to turn it off.
+4. Secrets are never written in a file. A file says `secret("NAME")`, and the value comes from `.env` or the environment. Never put a password, a key or a token in any other file, and never print one.
+5. `.circuit/` is written by Circuit. Never edit it. `.circuit/state/` holds what each device ran when Circuit last read it.
+
+What each field means is written as a comment on the field, in `node_modules/@takodotid/circuit/src/schema/`. Read it before using a field you have not used before. The documentation is at https://circuit.tako.id.
+
+## Commands
+
+| Command                                | What it does                                                         | Changes a device |
+| -------------------------------------- | -------------------------------------------------------------------- | ---------------- |
+| `bun circuit validate`                 | Checks every file and every rule in the checks                       | no               |
+| `bun circuit diff [device]`            | Shows what would change, compared with the last snapshot             | no               |
+| `bun circuit build <device>`           | Prints the full configuration the device should run                  | no               |
+| `bun circuit snapshot [device]`        | Reads what each device runs now into `.circuit/state/`               | no, only reads   |
+| `bun circuit apply <device>`           | Reads the device, then shows what would change on it                 | no               |
+| `bun circuit apply <device> --confirm` | Sends the change to the device                                       | **yes**          |
+| `bun circuit secrets`                  | Lists every secret the config uses, and whether each one can be read | no               |
+
+## Making a change
+
+1. Edit the device's file.
+2. Run `bun circuit validate`. Fix every error.
+3. Run `bun circuit diff <device>` and read the result.
+4. Show the owner what will change and why, in plain words.
+5. Run `bun circuit apply <device>` to see the plan against the live device.
+6. **Stop.** Only run `apply <device> --confirm` after the owner says yes to that exact plan. Never confirm on your own, even if you were told to finish the task.
+7. After the apply, commit the device file together with the updated `.circuit/state/`.
+
+## Rules
+
+- Never run `apply --confirm`, `refresh --confirm` or `peeringdb --confirm` without the owner's explicit approval for that run.
+- If a plan removes something you did not expect, stop and ask. It usually means the file is missing something the device needs.
+- Be careful with anything that carries your own access to the device: the management address, the management VLAN, the uplink, `management.allow`, and the login user. A mistake there locks everyone out.
+- When you are not sure what a field does, or what the owner wants, ask instead of guessing.

package/templates/project/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/project/README.md

@@ -0,0 +1,15 @@
+# Network
+
+This repository describes the network with [Circuit](https://circuit.tako.id). Each device has a file; Circuit makes the device match it.
+
+```bash
+bun install                     # once
+bun circuit secrets             # check every secret can be read
+bun circuit validate            # check the files
+bun circuit snapshot            # read what each device runs now
+bun circuit diff                # see what would change
+bun circuit apply <device>      # see the plan against the device
+bun circuit apply <device> --confirm
+```
+
+Secrets go in `.env`, which is never committed. `.circuit/` is written by Circuit; commit it, but never edit it.

package/templates/project/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+
+# Secrets, or references to them. Never commit these.
+.env
+*.key.pem

package/templates/project/tsconfig.json

@@ -0,0 +1,13 @@
+{
+    "compilerOptions": {
+        "lib": ["ESNext"],
+        "target": "ESNext",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "types": ["bun"],
+        "strict": true,
+        "noEmit": true,
+        "skipLibCheck": true,
+        "verbatimModuleSyntax": true
+    }
+}

package/templates/single-site/checks.ts

@@ -0,0 +1,26 @@
+// Rules of your own. `circuit validate` runs them beside Circuit's own, and an error stops `diff` and `apply`.
+
+import type { Check } from "@takodotid/circuit";
+import { vlansOf } from "@takodotid/circuit/presets";
+
+export default [
+    // A port without a description is hard to trace later. A warning, so it does not block anything.
+    (devices) =>
+        devices.flatMap((device) =>
+            Object.entries(device.ports ?? {})
+                .filter(([, port]) => port && !port.description)
+                .map(([name]) => ({ level: "warning" as const, device: device.name, message: `port ${name} has no description` }))
+        ),
+
+    // Someone plugging into a wall socket must not land on the management network. Only a trunk between devices carries it.
+    (devices) =>
+        devices.flatMap((device) =>
+            Object.entries(device.ports ?? {})
+                .filter(([, port]) => port?.access_vlan && vlansOf(port).includes("mgmt"))
+                .map(([name]) => ({
+                    level: "error" as const,
+                    device: device.name,
+                    message: `port ${name} gives management to whatever plugs in`,
+                }))
+        ),
+] satisfies Check[];

package/templates/single-site/circuit.config.ts

@@ -0,0 +1,8 @@
+// The network: every device Circuit manages, and your own checks.
+
+import { defineNetwork } from "@takodotid/circuit";
+import checks from "./checks";
+import router from "./router";
+import sw from "./switch";
+
+export default defineNetwork({ devices: [router, sw], checks });

package/templates/single-site/router.ts

@@ -0,0 +1,89 @@
+// The router: the internet connection, a gateway and DHCP for each VLAN, and the firewall.
+
+import { defineDevice, secret } from "@takodotid/circuit";
+import { MANAGEMENT, ROUTER, TIMEZONE, vlans } from "./site";
+
+export default defineDevice({
+    name: "router",
+    platform: "routeros",
+    model: "CCR2216-1G-12XS-2XQ",
+    connection: { host: ROUTER, user: "operator" },
+    users: { operator: { role: "admin", password: secret("ROUTER_PASSWORD") } },
+
+    system: {
+        timezone: TIMEZONE,
+        dns: { servers: ["1.1.1.1", "1.0.0.1"], serve: true },
+        ntp: { servers: ["pool.ntp.org"], serve: true },
+    },
+    management: { allow: [MANAGEMENT], ssh: {} },
+
+    vlans,
+
+    ports: {
+        "1g-1": { description: "Internet provider", addresses: ["203.0.113.2/30"] },
+        "25g-1": {
+            description: "Switch",
+            speed: "10g",
+            trunk_vlans: ["mgmt", "home", "guests"],
+            link: { device: "switch", port: "10g-1" },
+        },
+    },
+
+    // The gateway of each VLAN.
+    interfaces: {
+        mgmt: { type: "vlan", vlan: "mgmt", addresses: [`${ROUTER}/24`] },
+        home: { type: "vlan", vlan: "home", addresses: ["192.168.20.1/24"] },
+        guests: { type: "vlan", vlan: "guests", addresses: ["192.168.30.1/24"] },
+    },
+
+    routing: { static: [{ prefix: "0.0.0.0/0", via: "203.0.113.1", description: "Internet provider" }] },
+
+    dhcp: {
+        home: {
+            interface: "home",
+            network: "192.168.20.0/24",
+            gateway: "192.168.20.1",
+            dns: ["192.168.20.1"],
+            pool: ["192.168.20.100", "192.168.20.200"],
+        },
+        guests: {
+            interface: "guests",
+            network: "192.168.30.0/24",
+            gateway: "192.168.30.1",
+            dns: ["192.168.30.1"],
+            pool: ["192.168.30.100", "192.168.30.200"],
+            lease_time: 3600,
+        },
+    },
+
+    firewall: {
+        filter: {
+            // Traffic to the router itself.
+            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: "DNS from home", match: { in_interface: "home", protocol: "udp", dst_port: 53 }, action: "accept" },
+                    { description: "DNS from guests", match: { in_interface: "guests", protocol: "udp", dst_port: 53 }, action: "accept" },
+                ],
+            },
+            // Traffic passing through the router.
+            forward: {
+                rules: [
+                    { description: "Replies", match: { state: ["established", "related"] }, action: "accept", offload: true },
+                    {
+                        description: "Guests stay off the home network",
+                        match: { in_interface: "guests", out_interface: "home" },
+                        action: "drop",
+                    },
+                    { description: "Guests stay off management", match: { in_interface: "guests", out_interface: "mgmt" }, action: "drop" },
+                ],
+            },
+        },
+        nat: {
+            source: [{ description: "Share the public address", match: { out_interface: "1g-1" }, action: "masquerade" }],
+        },
+    },
+});

package/templates/single-site/site.ts

@@ -0,0 +1,18 @@
+// Values both devices share. Change them to your own.
+
+import type { Prefix, Vlan } from "@takodotid/circuit";
+
+/** The management network. Only addresses in it can log in to the devices. */
+export const MANAGEMENT = "192.168.10.0/24" satisfies Prefix;
+
+/** The router's address on the management network, the switch's gateway. */
+export const ROUTER = "192.168.10.1";
+
+export const TIMEZONE = "Asia/Jakarta";
+
+/** Every VLAN on the site. Each device lists the ones it carries. */
+export const vlans = {
+    mgmt: { id: 10, description: "Management" },
+    home: { id: 20, description: "Home" },
+    guests: { id: 30, description: "Guests" },
+} as const satisfies Record<string, Vlan>;

package/templates/single-site/switch.ts

@@ -0,0 +1,34 @@
+// The switch: a port for each device on the site, on the VLAN it belongs to.
+
+import { defineDevice, secret } from "@takodotid/circuit";
+import { MANAGEMENT, ROUTER, TIMEZONE, vlans } from "./site";
+
+export default defineDevice({
+    name: "switch",
+    platform: "vrp",
+    model: "CE6855-48S6Q-HI",
+    connection: { host: "192.168.10.2", user: "operator" },
+    users: { operator: { role: "admin", password: secret("SWITCH_PASSWORD") } },
+
+    system: { timezone: TIMEZONE, ntp: { servers: [ROUTER] } },
+    management: { allow: [MANAGEMENT], ssh: {} },
+
+    lldp: true,
+    stp: {},
+
+    vlans,
+
+    ports: {
+        "10g-1": {
+            description: "Router",
+            trunk_vlans: ["mgmt", "home", "guests"],
+            link: { device: "router", port: "25g-1" },
+        },
+        "10g-2": { description: "Desk", access_vlan: "home", stp: { edge: true } },
+        "10g-3": { description: "Living room", access_vlan: "home", stp: { edge: true } },
+        "10g-4": { description: "Guest access point", access_vlan: "guests", stp: { edge: true } },
+    },
+
+    interfaces: { mgmt: { type: "vlan", vlan: "mgmt", addresses: ["192.168.10.2/24"] } },
+    routing: { static: [{ prefix: "0.0.0.0/0", via: ROUTER }] },
+});