@homeflare/site 0.1.0

package/src/primitives.ts

@@ -0,0 +1,139 @@
+/**
+ * The value shapes a site file is made of. Each one refuses at decode time, naming its path,
+ * so a typo fails when the file is read rather than when a plan renames something.
+ *
+ * ⛔ LOWERCASE ONLY for DNS names. Cloudflare, OpenBao and ssh compare names as strings in
+ *   places, and `Mgmt.Example.com` is not `mgmt.example.com` to a principal list.
+ */
+import * as Schema from 'effect/Schema';
+
+/** One DNS label: `v`, `mgmt`, `n1`. Also the shape of every key a consumer looks up. */
+export const Label = Schema.String.check(
+  Schema.isPattern(/^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/, {
+    message: 'Expected a lowercase DNS label (a-z, 0-9, inner hyphens, at most 63)',
+  }),
+);
+
+/** A fully qualified name with at least two labels: `example.com`, `shop.example.net`. */
+export const Hostname = Schema.String.check(
+  Schema.isPattern(
+    /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]([a-z0-9-]{0,61}[a-z0-9])?$/,
+    { message: 'Expected a lowercase fully qualified hostname such as example.com' },
+  ),
+);
+
+/** A certificate name: a hostname, or one leading wildcard label. */
+export const CertificateName = Schema.String.check(
+  Schema.isPattern(
+    /^(\*\.)?([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]([a-z0-9-]{0,61}[a-z0-9])?$/,
+    { message: 'Expected a hostname, optionally with one leading *. wildcard' },
+  ),
+);
+
+const OCTET = '(25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])';
+
+/** A dotted-quad IPv4 address, every octet 0–255. */
+export const Ipv4 = Schema.String.check(
+  Schema.isPattern(new RegExp(`^(${OCTET}\\.){3}${OCTET}$`), {
+    message: 'Expected an IPv4 address such as 192.0.2.10',
+  }),
+);
+
+/** Parse `a.b.c.d/p` into a 32-bit base and a prefix length. `undefined` when malformed. */
+export function parseCidr(cidr: string): { base: number; prefix: number } | undefined {
+  const match = new RegExp(`^((${OCTET}\\.){3}${OCTET})/([0-9]{1,2})$`).exec(cidr);
+  if (match === null) return undefined;
+  const prefix = Number(match[match.length - 1]);
+  const base = (match[1] ?? '').split('.').reduce((acc, octet) => acc * 256 + Number(octet), 0);
+  return { base, prefix };
+}
+
+/**
+ * An IPv4 network, `/8` to `/30`, written at its network address.
+ *
+ * ⚠️ `192.0.2.5/24` is refused, not normalised. A host address with a prefix usually means
+ *   someone pasted an interface address where a network belongs; normalising it would hide
+ *   the mistake and derive every leg address from the wrong idea of the network.
+ */
+export const Ipv4Cidr = Schema.String.check(
+  Schema.makeFilter(
+    (value: string) => {
+      const parsed = parseCidr(value);
+      if (parsed === undefined) return 'Expected an IPv4 network such as 192.0.2.0/24';
+      if (parsed.prefix < 8 || parsed.prefix > 30) return 'Expected a prefix between /8 and /30';
+      const hostBits = 2 ** (32 - parsed.prefix);
+      if (parsed.base % hostBits !== 0) return 'Expected the network address (host bits zero)';
+      return undefined;
+    },
+    { expected: 'an IPv4 network' },
+  ),
+);
+
+/** A host's number on a network: `.11` on a /24 is 11. Checked against the prefix later. */
+export const HostNumber = Schema.Number.check(
+  Schema.isInt(),
+  Schema.isBetween({ minimum: 1, maximum: 16_777_214 }),
+);
+
+export const Port = Schema.Number.check(
+  Schema.isInt(),
+  Schema.isBetween({ minimum: 1, maximum: 65_535 }),
+);
+
+/** A Cloudflare account id: 32 lowercase hex characters. */
+export const AccountId = Schema.String.check(
+  Schema.isPattern(/^[0-9a-f]{32}$/, {
+    message: 'Expected a 32-character lowercase hex account id',
+  }),
+);
+
+/** A GitHub user or organisation login. GitHub itself allows uppercase here. */
+export const GithubOwner = Schema.String.check(
+  Schema.isPattern(/^[A-Za-z0-9]([A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/, {
+    message: 'Expected a GitHub login (letters, digits, inner hyphens)',
+  }),
+);
+
+/** An absolute POSIX path with no trailing slash: `/opt/example`. */
+export const AbsolutePath = Schema.String.check(
+  Schema.isPattern(/^(\/[^/\0]+)+$/, {
+    message: 'Expected an absolute path without a trailing slash',
+  }),
+);
+
+/** A semver version, as npm writes one: `0.1.0`, `1.0.0-rc.1`. */
+export const SemVer = Schema.String.check(
+  Schema.isPattern(/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/, { message: 'Expected a semver version' }),
+);
+
+/** A key into a `pinned` table: `alerts.d1`, `ssh-host.host`. Dotted, lowercase. */
+export const PinKey = Schema.String.check(
+  Schema.isPattern(/^[a-z0-9]+([._-][a-z0-9]+)*$/, {
+    message: 'Expected a lowercase dotted key such as alerts.d1',
+  }),
+);
+
+/**
+ * A physical resource name: Worker, D1, KV, R2, Durable Object class.
+ * ★ Case is allowed because Durable Object bindings name PascalCase classes.
+ */
+export const PhysicalName = Schema.String.check(
+  Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, {
+    message: 'Expected a resource name (letters, digits, dot, dash, underscore)',
+  }),
+);
+
+/**
+ * One SSH principal or policy entry.
+ * ⛔ No commas and no whitespace. OpenBao stores principal lists comma-joined, so an entry
+ *   holding a comma silently becomes two principals, and a stray space becomes a name no
+ *   host will ever present.
+ */
+export const ListEntry = Schema.String.check(
+  Schema.isPattern(/^[^\s,]+$/, { message: 'Expected one entry with no commas or whitespace' }),
+);
+
+/** A free-form identifier that must not be blank: cluster names, adopted ids, CNs. */
+export const NonBlank = Schema.String.check(
+  Schema.isPattern(/^\S(.*\S)?$/, { message: 'Expected a non-blank value without edge spaces' }),
+);

package/src/references.ts

@@ -0,0 +1,82 @@
+/**
+ * Checks that span fields: every zone, host and network a value names is declared.
+ *
+ * ★ WHY NOT IN THE SCHEMA. A struct-level filter reports one issue at the struct's own
+ *   path; these checks want to name the exact field (`services.grafana.host`), and they
+ *   want to report every broken reference at once rather than the first.
+ */
+import { lastHostNumber } from './net.ts';
+import type { Site } from './schema.ts';
+
+/** The zone key that means the apex itself. Reserved: a site may not declare it. */
+export const APEX_ZONE = 'apex';
+
+function hostHasZone(site: Site, host: string): boolean {
+  return Object.hasOwn(site.hosts, host) && site.hosts[host]?.zone !== undefined;
+}
+
+function checkHosts(site: Site, issues: string[]): void {
+  for (const [key, host] of Object.entries(site.hosts)) {
+    const zone = host.zone;
+    if (zone !== undefined && zone !== APEX_ZONE && !Object.hasOwn(site.zones, zone)) {
+      issues.push(`hosts.${key}.zone: "${zone}" is not a declared zone or "${APEX_ZONE}"`);
+    }
+    for (const [network, number] of Object.entries(host.legs ?? {})) {
+      const cidr = site.networks[network];
+      if (cidr === undefined) {
+        issues.push(`hosts.${key}.legs.${network}: "${network}" is not a declared network`);
+      } else if (number > lastHostNumber(cidr)) {
+        issues.push(`hosts.${key}.legs.${network}: host number ${number} does not fit ${network}`);
+      }
+    }
+  }
+}
+
+function checkZonedHost(site: Site, path: string, host: string, issues: string[]): void {
+  if (!Object.hasOwn(site.hosts, host)) {
+    issues.push(`${path}: "${host}" is not a declared host`);
+  } else if (!hostHasZone(site, host)) {
+    issues.push(`${path}: host "${host}" has no zone, so it has no hostname`);
+  }
+}
+
+function checkAccounts(site: Site, issues: string[]): void {
+  for (const [alias, account] of Object.entries(site.cloudflare.accounts)) {
+    const seen = new Set<string>();
+    for (const surface of account.surfaces) {
+      // ⚠️ A repeated surface derives the same mount name twice; the second declaration
+      //   would silently be the same mount, so a typo'd duplicate is refused here.
+      if (seen.has(surface)) {
+        issues.push(`cloudflare.accounts.${alias}.surfaces: "${surface}" is listed twice`);
+      }
+      seen.add(surface);
+    }
+  }
+}
+
+/** Every broken reference in `site`, each naming its path. Empty when the site is sound. */
+export function referenceIssues(site: Site): readonly string[] {
+  const issues: string[] = [];
+
+  if (Object.hasOwn(site.zones, APEX_ZONE)) {
+    issues.push(`zones.${APEX_ZONE}: reserved — a host with zone "${APEX_ZONE}" sits on the apex`);
+  }
+  checkHosts(site, issues);
+  for (const [key, cluster] of Object.entries(site.clusters)) {
+    for (const [i, member] of cluster.members.entries()) {
+      checkZonedHost(site, `clusters.${key}.members.${i}`, member, issues);
+    }
+  }
+  for (const [key, product] of Object.entries(site.products)) {
+    if (product.label !== undefined && product.domain !== undefined) {
+      issues.push(`products.${key}: set label OR domain, not both`);
+    }
+  }
+  for (const [key, service] of Object.entries(site.services)) {
+    checkZonedHost(site, `services.${key}.host`, service.host, issues);
+  }
+  checkZonedHost(site, 'vault.lan.host', site.vault.lan.host, issues);
+  checkAccounts(site, issues);
+
+  return issues;
+}

package/src/schema.ts

@@ -0,0 +1,144 @@
+/**
+ * The site file: BASE VALUES and PINNED values, nothing derived.
+ *
+ * ★ BASE VALUES are the few things every name is relative to — the apex, a handful of
+ *   labels, networks and hosts. `derive()` builds hostnames and addresses from them, so
+ *   swapping the apex changes every derived name by substitution and nothing else.
+ *
+ * ⛔ PINNED VALUES ARE NEVER DERIVED. Physical names (Workers, D1, KV, R2, Durable Objects)
+ *   follow no rule, and deriving one would REPLACE it: a derived D1 name deletes the data
+ *   behind the old one. Certificate hostnames on adopted certificates reissue and revoke
+ *   the certificate a host is still serving if they change. Adopted ids name objects that
+ *   already exist. Policy and SSH principal lists are explicit so a break-glass principal
+ *   can never vanish because a network leg was renamed.
+ *
+ * ⛔ UNKNOWN KEYS ARE REFUSED (see decode.ts). A misspelt optional field would otherwise
+ *   decode as "absent" and the file would look valid while saying less than its author
+ *   meant.
+ */
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import {
+  AbsolutePath,
+  AccountId,
+  CertificateName,
+  GithubOwner,
+  HostNumber,
+  Hostname,
+  Ipv4,
+  Ipv4Cidr,
+  Label,
+  ListEntry,
+  NonBlank,
+  PhysicalName,
+  PinKey,
+  Port,
+  SemVer,
+} from './primitives.ts';
+
+/** The site file format this package reads. A new format is a new literal, never a reuse. */
+export const SITE_FORMAT = 1;
+
+const emptyRecord = <S extends Schema.Top>(schema: S) =>
+  schema.pipe(Schema.withDecodingDefaultKey(Effect.succeed({})));
+
+const Scheme = Schema.Literals(['http', 'https']);
+
+/**
+ * A machine. Its FQDN is `<key>.<zone>`; its address on a network is that network's base
+ * plus `legs[network]`.
+ * ★ `zone: "apex"` places the host directly under the apex (`docs.<apex>`).
+ */
+const Host = Schema.Struct({
+  zone: Schema.optionalKey(Label),
+  aliases: Schema.optionalKey(Schema.Array(Label)),
+  legs: Schema.optionalKey(Schema.Record(Label, HostNumber)),
+});
+
+/** A public product: `<label ?? key>.<apex>`, or its own `domain`. Never both. */
+const Product = Schema.Struct({
+  label: Schema.optionalKey(Label),
+  domain: Schema.optionalKey(Hostname),
+});
+
+/** An internal endpoint on a declared host. ⛔ The scheme is explicit, never guessed. */
+const Service = Schema.Struct({ host: Label, port: Port, scheme: Scheme });
+
+const Account = Schema.Struct({
+  id: AccountId,
+  zones: Schema.Array(Hostname),
+  /** Each surface becomes an OpenBao mount `cloudflare-<alias>-<surface>`. */
+  surfaces: Schema.Array(Label),
+});
+
+const Vault = Schema.Struct({
+  /** `<vault-host>` = `<label>.<apex>`. */
+  label: Label,
+  /**
+   * `<vault-api-host>` = `<apiLabel>.<vault-host>`.
+   * ⚠️ NOT `vaultApi` beside a `vault` label. Measured 2026-09-21 on effect 4.0.0-rc.115:
+   *   constant-cased env names nest by prefix, so `HF_SITE_VAULT_API` made the provider
+   *   read `vault` as a record and the whole decode failed "Expected string". No field
+   *   name here may be another's name plus `_…`; tests/overrides.test.ts asserts it.
+   */
+  apiLabel: Label,
+  /**
+   * ⛔ PINNED IDENTITY: the `cluster_name` the vault reports on `sys/health`. Set at init,
+   *   never derived; plans compare it before touching anything (see identity.ts).
+   */
+  clusterName: NonBlank,
+  namespace: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed(''))),
+  port: Port.pipe(Schema.withDecodingDefaultKey(Effect.succeed(8200))),
+  /** The vault's address on the private Mesh path. Machines use it; strict TLS applies. */
+  meshAddress: Ipv4,
+  /** The LAN pass-through proxy: a declared host, its port, and its scheme. */
+  lan: Schema.Struct({ host: Label, port: Port, scheme: Scheme }),
+  oidcMount: Label.pipe(Schema.withDecodingDefaultKey(Effect.succeed('oidc'))),
+  /** The port `bao login -method=oidc` listens on for its localhost callback. */
+  cliCallbackPort: Port.pipe(Schema.withDecodingDefaultKey(Effect.succeed(8250))),
+});
+
+const Pinned = Schema.Struct({
+  names: emptyRecord(Schema.Record(PinKey, PhysicalName)),
+  certificates: emptyRecord(Schema.Record(PinKey, Schema.NonEmptyArray(CertificateName))),
+  adopted: emptyRecord(Schema.Record(PinKey, NonBlank)),
+  policies: emptyRecord(Schema.Record(PinKey, Schema.Array(ListEntry))),
+  sshPrincipals: emptyRecord(Schema.Record(PinKey, Schema.Array(ListEntry))),
+});
+
+export const SiteSchema = Schema.Struct({
+  /** The file format. Only {@link SITE_FORMAT} decodes. */
+  version: Schema.Literal(SITE_FORMAT),
+  /**
+   * The `@homeflare/site` version whose derive rules this file was reviewed against.
+   * ⛔ A repo refuses to load when its installed package differs (see guards.ts), so a
+   *   derive change can never rename live objects without someone bumping this line.
+   */
+  deriveVersion: SemVer,
+  /** ⛔ Only a `live` site may plan stage `live` (see guards.ts). */
+  kind: Schema.Literals(['live', 'testing', 'example']),
+  apex: Hostname,
+  /**
+   * Zone suffixes under the apex: `{ "mgmt": "mgmt" }` gives `mgmt.<apex>`.
+   * ⛔ `mgmt` is required (it is `<mgmt-zone>`), and the key `apex` is reserved.
+   */
+  zones: Schema.StructWithRest(Schema.Struct({ mgmt: Label }), [Schema.Record(Label, Label)]),
+  networks: Schema.Record(Label, Ipv4Cidr),
+  hosts: Schema.Record(Label, Host),
+  clusters: emptyRecord(Schema.Record(Label, Schema.Struct({ members: Schema.Array(Label) }))),
+  products: emptyRecord(Schema.Record(Label, Product)),
+  services: emptyRecord(Schema.Record(Label, Service)),
+  cloudflare: Schema.Struct({
+    accounts: Schema.Record(Label, Account),
+    access: Schema.Struct({ team: Label }),
+  }),
+  github: Schema.Struct({ owner: GithubOwner }),
+  paths: Schema.Struct({ estateRoot: AbsolutePath }),
+  vault: Vault,
+  pinned: Pinned.pipe(Schema.withDecodingDefaultKey(Effect.succeed({}))),
+});
+
+/** A decoded site: defaults applied, every value checked. */
+export type Site = typeof SiteSchema.Type;
+/** What a site file may contain before defaults are applied. */
+export type SiteInput = typeof SiteSchema.Encoded;

package/src/tokens.ts

@@ -0,0 +1,60 @@
+/**
+ * The placeholders public docs use instead of estate values.
+ *
+ * ⛔ A PUBLIC DOC NEVER NAMES A LIVE VALUE. It writes `<vault-host>`, and anyone reading
+ *   it substitutes their own. `tokenValues(site)` is that substitution for one site; a
+ *   leak gate builds its needles from `tokenValues(liveSite)` in memory, so the live
+ *   values never have to be written down anywhere else.
+ *
+ * ★ `<cluster>` HAS NO SINGLE VALUE. It stands for any key of `site.clusters` (as
+ *   `<alias>` and `<surface>` do inside `cloudflare-<alias>-<surface>`), so it is listed
+ *   for doc lint but never substituted.
+ */
+import { derive } from './derive.ts';
+import type { Site } from './schema.ts';
+
+export const SITE_TOKENS = {
+  '<apex>': 'the apex domain every derived name hangs off',
+  '<vault-host>': 'the vault UI hostname: <vault label>.<apex>',
+  '<vault-api-host>': 'the vault public API hostname: <api label>.<vault-host>',
+  '<mgmt-zone>': 'the management zone: <mgmt label>.<apex>',
+  '<access-team>': 'the Cloudflare Access team name (<access-team>.cloudflareaccess.com)',
+  '<github-owner>': 'the GitHub user or organisation that owns the repos',
+  '<estate-root>': 'the absolute directory holding host-local estate files',
+  '<cluster>': 'any key of site.clusters — a variable, never substituted',
+} as const;
+
+export type SiteToken = keyof typeof SITE_TOKENS;
+
+/** Tokens with exactly one value per site. */
+export type ValuedToken = Exclude<SiteToken, '<cluster>'>;
+
+/** Each single-valued token's value for `site`. */
+export function tokenValues(site: Site): Readonly<Record<ValuedToken, string>> {
+  const derived = derive(site);
+  return {
+    '<apex>': site.apex,
+    '<vault-host>': derived.vault.host,
+    '<vault-api-host>': derived.vault.apiHost,
+    '<mgmt-zone>': derived.mgmtZone,
+    '<access-team>': site.cloudflare.access.team,
+    '<github-owner>': site.github.owner,
+    '<estate-root>': site.paths.estateRoot,
+  };
+}
+
+/**
+ * Replace every single-valued token in `text` with its value for `site`.
+ * ★ ONE PASS, longest token first in the alternation. A value is never read again, so a
+ *   value that itself contains a token stays literal. ⚠️ Measured 2026-09-21: the earlier
+ *   token-by-token loop rendered an estate root of `/opt/<apex>` as `/opt/example.com`.
+ */
+export function renderTokens(text: string, site: Site): string {
+  const values: Readonly<Record<string, string>> = tokenValues(site);
+  const tokens = Object.keys(values).sort((a, b) => b.length - a.length);
+  const pattern = new RegExp(
+    tokens.map((t) => t.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|'),
+    'g',
+  );
+  return text.replaceAll(pattern, (token) => values[token] ?? token);
+}

package/src/version.ts

@@ -0,0 +1,2 @@
+// ⛔ GENERATED by scripts/sync-versions.ts — do not edit. Source: package.json.
+export const VERSION: string = '0.1.0';