@homeflare/site 0.1.0

package/dist/schema.d.ts

@@ -0,0 +1,100 @@
+import * as Schema from 'effect/Schema';
+/** The site file format this package reads. A new format is a new literal, never a reuse. */
+export declare const SITE_FORMAT = 1;
+export declare const SiteSchema: Schema.Struct<{
+    /** The file format. Only {@link SITE_FORMAT} decodes. */
+    readonly version: Schema.Literal<1>;
+    /**
+     * 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.
+     */
+    readonly deriveVersion: Schema.String;
+    /** ⛔ Only a `live` site may plan stage `live` (see guards.ts). */
+    readonly kind: Schema.Literals<readonly ["live", "testing", "example"]>;
+    readonly apex: Schema.String;
+    /**
+     * Zone suffixes under the apex: `{ "mgmt": "mgmt" }` gives `mgmt.<apex>`.
+     * ⛔ `mgmt` is required (it is `<mgmt-zone>`), and the key `apex` is reserved.
+     */
+    readonly zones: Schema.StructWithRest<Schema.Struct<{
+        readonly mgmt: Schema.String;
+    }>, readonly [Schema.$Record<Schema.String, Schema.String>]>;
+    readonly networks: Schema.$Record<Schema.String, Schema.String>;
+    readonly hosts: Schema.$Record<Schema.String, Schema.Struct<{
+        readonly zone: Schema.optionalKey<Schema.String>;
+        readonly aliases: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly legs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Number>>;
+    }>>;
+    readonly clusters: Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.Struct<{
+        readonly members: Schema.$Array<Schema.String>;
+    }>>, never>;
+    readonly products: Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.Struct<{
+        readonly label: Schema.optionalKey<Schema.String>;
+        readonly domain: Schema.optionalKey<Schema.String>;
+    }>>, never>;
+    readonly services: Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.Struct<{
+        readonly host: Schema.String;
+        readonly port: Schema.Number;
+        readonly scheme: Schema.Literals<readonly ["http", "https"]>;
+    }>>, never>;
+    readonly cloudflare: Schema.Struct<{
+        readonly accounts: Schema.$Record<Schema.String, Schema.Struct<{
+            readonly id: Schema.String;
+            readonly zones: Schema.$Array<Schema.String>;
+            /** Each surface becomes an OpenBao mount `cloudflare-<alias>-<surface>`. */
+            readonly surfaces: Schema.$Array<Schema.String>;
+        }>>;
+        readonly access: Schema.Struct<{
+            readonly team: Schema.String;
+        }>;
+    }>;
+    readonly github: Schema.Struct<{
+        readonly owner: Schema.String;
+    }>;
+    readonly paths: Schema.Struct<{
+        readonly estateRoot: Schema.String;
+    }>;
+    readonly vault: Schema.Struct<{
+        /** `<vault-host>` = `<label>.<apex>`. */
+        readonly label: Schema.String;
+        /**
+         * `<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.
+         */
+        readonly apiLabel: Schema.String;
+        /**
+         * ⛔ 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).
+         */
+        readonly clusterName: Schema.String;
+        readonly namespace: Schema.withDecodingDefaultKey<Schema.String, never>;
+        readonly port: Schema.withDecodingDefaultKey<Schema.Number, never>;
+        /** The vault's address on the private Mesh path. Machines use it; strict TLS applies. */
+        readonly meshAddress: Schema.String;
+        /** The LAN pass-through proxy: a declared host, its port, and its scheme. */
+        readonly lan: Schema.Struct<{
+            readonly host: Schema.String;
+            readonly port: Schema.Number;
+            readonly scheme: Schema.Literals<readonly ["http", "https"]>;
+        }>;
+        readonly oidcMount: Schema.withDecodingDefaultKey<Schema.String, never>;
+        /** The port `bao login -method=oidc` listens on for its localhost callback. */
+        readonly cliCallbackPort: Schema.withDecodingDefaultKey<Schema.Number, never>;
+    }>;
+    readonly pinned: Schema.withDecodingDefaultKey<Schema.Struct<{
+        readonly names: Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>;
+        readonly certificates: Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.NonEmptyArray<Schema.String>>, never>;
+        readonly adopted: Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.String>, never>;
+        readonly policies: Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.$Array<Schema.String>>, never>;
+        readonly sshPrincipals: Schema.withDecodingDefaultKey<Schema.$Record<Schema.String, Schema.$Array<Schema.String>>, never>;
+    }>, never>;
+}>;
+/** 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;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAmBxC,6FAA6F;AAC7F,eAAO,MAAM,WAAW,IAAI,CAAC;AAqE7B,eAAO,MAAM,UAAU;IACrB,yDAAyD;;IAEzD;;;;OAIG;;IAEH,kEAAkE;;;IAGlE;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;YAtDH,4EAA4E;;;;;;;;;;;;;;QAK5E,yCAAyC;;QAEzC;;;;;;WAMG;;QAEH;;;WAGG;;;;QAIH,yFAAyF;;QAEzF,6EAA6E;;;;;;;QAG7E,+EAA+E;;;;;;;;;;EA0C/E,CAAC;AAEH,6DAA6D;AAC7D,MAAM,MAAM,IAAI,GAAG,OAAO,UAAU,CAAC,IAAI,CAAC;AAC1C,gEAAgE;AAChE,MAAM,MAAM,SAAS,GAAG,OAAO,UAAU,CAAC,OAAO,CAAC"}

package/dist/tokens.d.ts

@@ -0,0 +1,24 @@
+import type { Site } from './schema.ts';
+export declare const SITE_TOKENS: {
+    readonly '<apex>': 'the apex domain every derived name hangs off';
+    readonly '<vault-host>': 'the vault UI hostname: <vault label>.<apex>';
+    readonly '<vault-api-host>': 'the vault public API hostname: <api label>.<vault-host>';
+    readonly '<mgmt-zone>': 'the management zone: <mgmt label>.<apex>';
+    readonly '<access-team>': 'the Cloudflare Access team name (<access-team>.cloudflareaccess.com)';
+    readonly '<github-owner>': 'the GitHub user or organisation that owns the repos';
+    readonly '<estate-root>': 'the absolute directory holding host-local estate files';
+    readonly '<cluster>': 'any key of site.clusters — a variable, never substituted';
+};
+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 declare function tokenValues(site: Site): Readonly<Record<ValuedToken, string>>;
+/**
+ * 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 declare function renderTokens(text: string, site: Site): string;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAExC,eAAO,MAAM,WAAW;aACtB,QAAQ,EAAE,8CAA8C;aACxD,cAAc,EAAE,6CAA6C;aAC7D,kBAAkB,EAAE,yDAAyD;aAC7E,aAAa,EAAE,0CAA0C;aACzD,eAAe,EAAE,sEAAsE;aACvF,gBAAgB,EAAE,qDAAqD;aACvE,eAAe,EAAE,wDAAwD;aACzE,WAAW,EAAE,0DAA0D;CAC/D,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,WAAW,CAAC;AAEjD,8CAA8C;AAC9C,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;AAE1D,mDAAmD;AACnD,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAW7E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,CAQ7D"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,OAAO,EAAE,MAAgB,CAAC"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@homeflare/site",
+  "version": "0.1.0",
+  "description": "One typed site config: base values, pinned names, and every hostname and address derived from them.",
+  "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/site#readme",
+  "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
+  "license": "MIT",
+  "author": "Timothy Schneider",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taslabs-net/homeflare-kit.git",
+    "directory": "packages/site"
+  },
+  "files": [
+    "dist",
+    "src",
+    "site.example.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./load": {
+      "types": "./dist/load.d.ts",
+      "default": "./dist/load.js"
+    },
+    "./site.example.json": "./site.example.json",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-rc.115"
+  }
+}

package/site.example.json

@@ -0,0 +1,81 @@
+{
+  "version": 1,
+  "deriveVersion": "0.1.0",
+  "kind": "example",
+  "apex": "example.com",
+  "zones": { "mgmt": "mgmt", "lab": "lab" },
+  "networks": {
+    "mgmt": "192.0.2.0/24",
+    "lab": "198.51.100.0/24",
+    "services": "203.0.113.0/24",
+    "storage": "198.18.4.0/24"
+  },
+  "hosts": {
+    "hub": {
+      "zone": "mgmt",
+      "aliases": ["gateway"],
+      "legs": { "mgmt": 250, "services": 250 }
+    },
+    "n1": { "zone": "mgmt", "legs": { "mgmt": 11, "lab": 11 } },
+    "n2": { "zone": "mgmt", "legs": { "mgmt": 12, "lab": 12 } },
+    "n3": { "zone": "mgmt", "legs": { "mgmt": 13, "lab": 13 } },
+    "backup": { "zone": "lab", "legs": { "mgmt": 7, "storage": 7 } },
+    "docs": { "zone": "apex" }
+  },
+  "clusters": { "c1": { "members": ["n1", "n2", "n3"] } },
+  "products": {
+    "alerts": {},
+    "wiki": { "label": "kb" },
+    "shop": { "domain": "shop.example.net" }
+  },
+  "services": {
+    "grafana": { "host": "hub", "port": 3000, "scheme": "http" }
+  },
+  "cloudflare": {
+    "accounts": {
+      "main": {
+        "id": "00000000000000000000000000000001",
+        "zones": ["example.com", "example.org"],
+        "surfaces": ["dns", "platform", "security", "access"]
+      },
+      "lab": {
+        "id": "00000000000000000000000000000002",
+        "zones": ["example.net"],
+        "surfaces": ["dns"]
+      }
+    },
+    "access": { "team": "example-team" }
+  },
+  "github": { "owner": "example-org" },
+  "paths": { "estateRoot": "/opt/example" },
+  "vault": {
+    "label": "v",
+    "apiLabel": "api",
+    "clusterName": "example-vault",
+    "meshAddress": "198.18.0.2",
+    "lan": { "host": "hub", "port": 8200, "scheme": "http" }
+  },
+  "pinned": {
+    "names": { "alerts.d1": "example-alerts", "alerts.worker": "example-alerts-api" },
+    "certificates": { "vault.origin": ["v.example.com", "api.v.example.com"] },
+    "adopted": {
+      "access.admin-policy": "00000000-0000-4000-8000-000000000001",
+      "backup.datastore": "example-store"
+    },
+    "policies": { "access.admins": ["alice@example.com"] },
+    "sshPrincipals": {
+      "ssh-host.host": [
+        "example.com",
+        "mgmt.example.com",
+        "hub",
+        "gateway",
+        "192.0.2.250",
+        "n1",
+        "n2",
+        "n3",
+        "192.0.2.11",
+        "198.51.100.11"
+      ]
+    }
+  }
+}

package/src/checkout.ts

@@ -0,0 +1,109 @@
+/**
+ * Is the site file committed, unmodified, on `main`?
+ *
+ * ⛔ NODE-ONLY (spawns git). Imported by `@homeflare/site/load`, never by the main entry.
+ *
+ * ★ WHY THE LOADER ASKS. Live plans must run on reviewed values. A site file edited in a
+ *   working tree, or read from a feature branch, would plan whatever it says — and a plan
+ *   against live state is where an unreviewed rename becomes a replace. `siteDev` (the
+ *   `--site-dev` flag in a consumer's CLI) is the explicit, visible way around it.
+ *
+ * ★ DIRTINESS IS THE FILE'S OWN, not the whole checkout's. Unrelated uncommitted work in
+ *   the repo holding the site file says nothing about the values being loaded, and would
+ *   otherwise block every deploy while someone edits a doc.
+ */
+import { execFile } from 'node:child_process';
+import { realpath } from 'node:fs/promises';
+import { basename, dirname } from 'node:path';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+
+/**
+ * ⚠️ GIT_* FROM THE CALLER'S ENVIRONMENT IS DROPPED. Git exports `GIT_DIR` (and friends)
+ *   to hooks, and `-C <dir>` does not override an exported `GIT_DIR`. Measured 2026-09-21:
+ *   `GIT_DIR=<some repo>/.git git -C <a directory outside any repo> symbolic-ref HEAD`
+ *   printed that other repo's branch. A loader run from a pre-push hook would ask about
+ *   the HOOK's repository, and answer "clean, on main" for a file it never looked at.
+ * ★ `GIT_LITERAL_PATHSPECS=1` is the one git variable set back: the file name is a name,
+ *   never a glob. Without it `site[1].json` would match a tracked `site1.json`.
+ */
+function gitEnv(): NodeJS.ProcessEnv {
+  return {
+    ...Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith('GIT_'))),
+    GIT_LITERAL_PATHSPECS: '1',
+  };
+}
+
+export interface CheckoutState {
+  /** The checked-out branch, or `undefined` on a detached HEAD. */
+  readonly branch: string | undefined;
+  /** Git knows the file (⚠️ an ignored or untracked file was never reviewed). */
+  readonly tracked: boolean;
+  /**
+   * The file's bytes differ from HEAD, staged or not.
+   * ⚠️ Compared by BLOB HASH, not only by `git status`. Measured 2026-09-21: after
+   *   `git update-index --skip-worktree` (the usual way to keep a local config tweak),
+   *   `status --porcelain` printed nothing for an edited site file, and a status-only
+   *   guard loaded the edited apex as "clean, on main".
+   */
+  readonly dirty: boolean;
+}
+
+async function git(dir: string, args: readonly string[]): Promise<string | undefined> {
+  try {
+    const { stdout } = await run('git', ['-C', dir, ...args], { encoding: 'utf8', env: gitEnv() });
+    return stdout.trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/** `realpath`, or the path unchanged when it cannot be resolved (the git calls then fail). */
+async function resolved(file: string): Promise<string> {
+  try {
+    return await realpath(file);
+  } catch {
+    return file;
+  }
+}
+
+/**
+ * The file's checkout state, or `undefined` when it is not inside a git work tree.
+ *
+ * ⚠️ THE REAL FILE IS CHECKED, NOT THE LINK. Measured 2026-09-21: a committed symlink whose
+ *   target lived outside the repository passed as "clean, on main" while the target was
+ *   edited freely — git tracks the link's target PATH, not the bytes behind it. Resolving
+ *   first makes that target "not inside a git checkout", which refuses.
+ */
+export async function readCheckout(file: string): Promise<CheckoutState | undefined> {
+  const real = await resolved(file);
+  const dir = dirname(real);
+  const name = basename(real);
+  if ((await git(dir, ['rev-parse', '--is-inside-work-tree'])) !== 'true') return undefined;
+  // ★ symbolic-ref, not `rev-parse --abbrev-ref`: it answers on an unborn branch too, and
+  //   fails (→ undefined) on a detached HEAD instead of printing the word "HEAD".
+  const branch = await git(dir, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+  const tracked = (await git(dir, ['ls-files', '--error-unmatch', '--', name])) !== undefined;
+  const status = await git(dir, ['status', '--porcelain', '--', name]);
+  // ★ hash-object applies the path's clean filters, so it names the blob git WOULD store;
+  //   HEAD:./<name> is the blob that was committed. Either failing counts as dirty.
+  const onDisk = await git(dir, ['hash-object', '--', name]);
+  const committed = await git(dir, ['rev-parse', '--verify', '--quiet', `HEAD:./${name}`]);
+  const differs = onDisk === undefined || committed === undefined || onDisk !== committed;
+  return { branch, tracked, dirty: status === undefined || status !== '' || differs };
+}
+
+/** Why `state` is not a reviewed checkout of `branch`, or `undefined` when it is. */
+export function checkoutProblem(
+  state: CheckoutState | undefined,
+  branch: string,
+): string | undefined {
+  if (state === undefined) return 'it is not inside a git checkout';
+  if (!state.tracked) return 'it is not committed (untracked or ignored)';
+  if (state.dirty) return 'it has uncommitted changes';
+  if (state.branch !== branch) {
+    return `the checkout is on ${state.branch === undefined ? 'a detached HEAD' : `"${state.branch}"`}, not "${branch}"`;
+  }
+  return undefined;
+}

package/src/decode.ts

@@ -0,0 +1,99 @@
+/**
+ * Decode a site from plain data. Runtime-neutral: no filesystem, no environment.
+ *
+ * ★ Workers and scripts that already hold the JSON (a binding, a fetched file) call
+ *   `decodeSite`. Scripts that read `HF_SITE_FILE` call `loadSite` from
+ *   `@homeflare/site/load`, which ends up here too.
+ */
+import * as Cause from 'effect/Cause';
+import * as Exit from 'effect/Exit';
+import * as Schema from 'effect/Schema';
+import * as SchemaIssue from 'effect/SchemaIssue';
+import { SiteError } from './errors.ts';
+import { checkDeriveVersion } from './guards.ts';
+import { referenceIssues } from './references.ts';
+import { type Site, SiteSchema } from './schema.ts';
+import { VERSION } from './version.ts';
+
+/**
+ * ⛔ `onExcessProperty: 'error'` IS LOAD-BEARING, twice over. Measured 2026-09-21 on
+ *   effect 4.0.0-rc.115: with the default (`ignore`), a misspelt field is dropped, AND a
+ *   record entry whose key fails the key schema (`"Mgmt"` in `networks`) is dropped too —
+ *   the file decodes, one network short, with no error at all.
+ * ⚠️ With it on, that bad record key reports as "excess property", which reads oddly.
+ *   `formatIssues` rewrites it to say what it actually means.
+ */
+const strict = Schema.decodeUnknownExit(SiteSchema, { onExcessProperty: 'error', errors: 'all' });
+const standard = SchemaIssue.makeFormatterStandardSchemaV1();
+
+const EXCESS = 'Expected no excess property';
+
+/**
+ * `pinned.certificates["vault.origin"].0` — a key that itself holds a dot is bracketed,
+ * or the path would read as two levels that do not exist.
+ */
+export function joinPath(segments: readonly string[]): string {
+  return segments
+    .map((segment, i) => {
+      if (segment.includes('.')) return `[${JSON.stringify(segment)}]`;
+      return i === 0 ? segment : `.${segment}`;
+    })
+    .join('');
+}
+
+/** Render a schema issue as `path: problem` lines, dropping a leading `skip` segment. */
+export function formatIssues(issue: SchemaIssue.Issue, skip?: string): readonly string[] {
+  return standard(issue).issues.map((entry) => {
+    const segments = (entry.path ?? []).map((part) =>
+      typeof part === 'object' && part !== null ? String(part.key) : String(part),
+    );
+    if (skip !== undefined && segments[0] === skip) segments.shift();
+    const path = segments.length === 0 ? '(root)' : joinPath(segments);
+    const message =
+      entry.message === EXCESS
+        ? 'unknown key (a misspelt field, or a record key that is not a lowercase label)'
+        : entry.message;
+    return `${path}: ${message}`;
+  });
+}
+
+/** Schema-only decode. Throws `decode` listing every problem, each with its path. */
+export function decodeStrict(input: unknown): Site {
+  const exit = strict(input);
+  if (Exit.isSuccess(exit)) return exit.value;
+  const error = Cause.squash(exit.cause);
+  if (Schema.isSchemaError(error)) {
+    throw new SiteError(
+      'decode',
+      'the site file does not match the schema',
+      formatIssues(error.issue),
+    );
+  }
+  throw error;
+}
+
+export interface ValidateOptions {
+  /**
+   * The `@homeflare/site` version to hold `deriveVersion` against. Defaults to the
+   * installed one — which is the point; override only to test the refusal.
+   */
+  readonly installed?: string;
+}
+
+/** Cross-field references, then the derive-version guard. Returns the same site. */
+export function validateSite(site: Site, options: ValidateOptions = {}): Site {
+  const issues = referenceIssues(site);
+  if (issues.length > 0) {
+    throw new SiteError('reference', 'the site file names things it does not declare', issues);
+  }
+  checkDeriveVersion(site, options.installed ?? VERSION);
+  return site;
+}
+
+/**
+ * Decode and validate a site from plain data (already-parsed JSON).
+ * Throws {@link SiteError}: `decode`, `reference` or `derive-version`.
+ */
+export function decodeSite(input: unknown, options: ValidateOptions = {}): Site {
+  return validateSite(decodeStrict(input), options);
+}

package/src/derive.ts

@@ -0,0 +1,188 @@
+/**
+ * `derive(site)`: every hostname, address, zone suffix, Access URL, OIDC redirect and
+ * vault mount name, built from base values. Pure — same site in, same names out.
+ *
+ * ⛔ DERIVE ONLY WHAT FOLLOWS A RULE. Physical names, certificate hostnames, adopted ids
+ *   and policy / principal lists are PINNED (see pins.ts). Anything added here must be
+ *   a pure function of base values, or the relativity test stops meaning anything.
+ *
+ * ⛔ UNKNOWN KEYS THROW. `productHost('typo')` refuses, naming what is declared. It never
+ *   falls back to `typo.<apex>`: a plausible default is how a typo becomes a DNS record.
+ *
+ * ★ The result is plain data plus lookup methods. `JSON.stringify(derive(site))` is the
+ *   whole rendering (methods drop out), which is what the leak and relativity tests read.
+ */
+import { SiteError, lookup, unknownKey } from './errors.ts';
+import { addressOn } from './net.ts';
+import { APEX_ZONE } from './references.ts';
+import type { Site } from './schema.ts';
+
+export interface DerivedHost {
+  /** `<key>.<zone>`; absent when the host declares no zone. */
+  readonly fqdn?: string;
+  /** Network key → address on that network. */
+  readonly addresses: Readonly<Record<string, string>>;
+}
+
+export interface DerivedVault {
+  /** `<vault-host>`: the browser / UI hostname. */
+  readonly host: string;
+  /** `<vault-api-host>`: the public API hostname. */
+  readonly apiHost: string;
+  /** `https://<vault-api-host>` — the public API. Humans; machines use Mesh or the LAN. */
+  readonly publicAddr: string;
+  /** `https://<mesh address>:<port>` — machines over the private Mesh path. */
+  readonly meshAddr: string;
+  /** The LAN pass-through proxy, as a `BAO_ADDR`. */
+  readonly lanAddr: string;
+  readonly namespace: string;
+  /** Browser callback on `<vault-host>`, then the CLI's localhost listener. */
+  readonly oidcRedirects: readonly string[];
+}
+
+export interface DerivedAccess {
+  readonly team: string;
+  /**
+   * `https://<team>.cloudflareaccess.com`. ★ Named for `verifyAccessJwt`'s `teamDomain`
+   *   option in `@homeflare/cloudflare`, so it passes straight through.
+   */
+  readonly teamDomain: string;
+  /** The JWKS endpoint Access signs with. */
+  readonly certsUrl: string;
+}
+
+export interface Derived {
+  readonly apex: string;
+  /** Zone key → FQDN (`mgmt` → `mgmt.<apex>`). */
+  readonly zones: Readonly<Record<string, string>>;
+  /** `<mgmt-zone>`. */
+  readonly mgmtZone: string;
+  readonly vault: DerivedVault;
+  readonly access: DerivedAccess;
+  readonly hosts: Readonly<Record<string, DerivedHost>>;
+  /** Product key → public hostname. */
+  readonly products: Readonly<Record<string, string>>;
+  /** Service key → URL. */
+  readonly services: Readonly<Record<string, string>>;
+  /** Cluster key → member FQDNs, in declared order. */
+  readonly clusters: Readonly<Record<string, readonly string[]>>;
+  /** Every `cloudflare-<alias>-<surface>` mount, in declared order. */
+  readonly cloudflareMounts: readonly string[];
+
+  /** A zone's FQDN. `"apex"` is the apex itself. */
+  zone(key: string): string;
+  /** A host's FQDN. Throws when the host is unknown or has no zone. */
+  host(key: string): string;
+  /** A host's address on a network. Throws when either is unknown or not a leg. */
+  address(host: string, network: string): string;
+  productHost(key: string): string;
+  /** `https://<productHost>`. */
+  productUrl(key: string): string;
+  serviceUrl(key: string): string;
+  clusterMembers(key: string): readonly string[];
+  /** Throws when the alias is unknown or that account does not list the surface. */
+  cloudflareMount(alias: string, surface: string): string;
+  accountId(alias: string): string;
+}
+
+function zoneOf(site: Site, key: string): string {
+  if (key === APEX_ZONE) return site.apex;
+  return `${lookup('zone', site.zones, key)}.${site.apex}`;
+}
+
+function deriveHosts(site: Site): Record<string, DerivedHost> {
+  const out: Record<string, DerivedHost> = {};
+  for (const [key, host] of Object.entries(site.hosts)) {
+    const addresses: Record<string, string> = {};
+    for (const [network, number] of Object.entries(host.legs ?? {})) {
+      addresses[network] = addressOn(lookup('network', site.networks, network), number);
+    }
+    out[key] = {
+      ...(host.zone === undefined ? {} : { fqdn: `${key}.${zoneOf(site, host.zone)}` }),
+      addresses,
+    };
+  }
+  return out;
+}
+
+function mapRecord<V, R>(record: Readonly<Record<string, V>>, f: (value: V, key: string) => R) {
+  const out: Record<string, R> = {};
+  for (const [key, value] of Object.entries(record)) out[key] = f(value, key);
+  return out;
+}
+
+export function derive(site: Site): Derived {
+  const hosts = deriveHosts(site);
+  const hostFqdn = (key: string): string => {
+    const fqdn = lookup('host', hosts, key).fqdn;
+    if (fqdn === undefined) {
+      throw new SiteError('unknown-key', `host "${key}" has no zone, so it has no hostname`);
+    }
+    return fqdn;
+  };
+
+  const vaultHost = `${site.vault.label}.${site.apex}`;
+  const apiHost = `${site.vault.apiLabel}.${vaultHost}`;
+  const { lan } = site.vault;
+  const teamDomain = `https://${site.cloudflare.access.team}.cloudflareaccess.com`;
+
+  const products = mapRecord(
+    site.products,
+    (p, key) => p.domain ?? `${p.label ?? key}.${site.apex}`,
+  );
+  const services = mapRecord(site.services, (s) => `${s.scheme}://${hostFqdn(s.host)}:${s.port}`);
+  const clusters = mapRecord(site.clusters, (c) => c.members.map(hostFqdn));
+  const accounts = site.cloudflare.accounts;
+  const cloudflareMounts = Object.entries(accounts).flatMap(([alias, account]) =>
+    account.surfaces.map((surface) => `cloudflare-${alias}-${surface}`),
+  );
+
+  return {
+    apex: site.apex,
+    zones: mapRecord(site.zones, (_label, key) => zoneOf(site, key)),
+    mgmtZone: zoneOf(site, 'mgmt'),
+    vault: {
+      host: vaultHost,
+      apiHost,
+      publicAddr: `https://${apiHost}`,
+      meshAddr: `https://${site.vault.meshAddress}:${site.vault.port}`,
+      lanAddr: `${lan.scheme}://${hostFqdn(lan.host)}:${lan.port}`,
+      namespace: site.vault.namespace,
+      oidcRedirects: [
+        `https://${vaultHost}/ui/vault/auth/${site.vault.oidcMount}/oidc/callback`,
+        `http://localhost:${site.vault.cliCallbackPort}/oidc/callback`,
+      ],
+    },
+    access: {
+      team: site.cloudflare.access.team,
+      teamDomain,
+      certsUrl: `${teamDomain}/cdn-cgi/access/certs`,
+    },
+    hosts,
+    products,
+    services,
+    clusters,
+    cloudflareMounts,
+
+    zone: (key) => zoneOf(site, key),
+    host: hostFqdn,
+    address: (host, network) => {
+      const addresses = lookup('host', hosts, host).addresses;
+      if (!Object.hasOwn(addresses, network))
+        unknownKey(`network leg of host "${host}"`, network, Object.keys(addresses));
+      return addresses[network] as string;
+    },
+    productHost: (key) => lookup('product', products, key),
+    productUrl: (key) => `https://${lookup('product', products, key)}`,
+    serviceUrl: (key) => lookup('service', services, key),
+    clusterMembers: (key) => lookup('cluster', clusters, key),
+    cloudflareMount: (alias, surface) => {
+      const account = lookup('cloudflare account', accounts, alias);
+      if (!account.surfaces.includes(surface)) {
+        unknownKey(`surface of account "${alias}"`, surface, account.surfaces);
+      }
+      return `cloudflare-${alias}-${surface}`;
+    },
+    accountId: (alias) => lookup('cloudflare account', accounts, alias).id,
+  };
+}