@homeflare/site 0.1.0

package/src/errors.ts

@@ -0,0 +1,60 @@
+/**
+ * The one error this package throws.
+ *
+ * ★ ONE CLASS, A `code` TO SWITCH ON. Callers mostly print the message and stop; the few
+ *   that branch (a scaffold harness skipping `derive-version` in a dry run, say) branch on
+ *   `code`, which is stable, rather than on message text, which is not.
+ *
+ * ⛔ Messages name paths, keys and the fix — never a value from a live file beyond the
+ *   one being complained about. A site file is private, and an error string ends up in CI
+ *   logs.
+ */
+
+export type SiteErrorCode =
+  /** The file does not match the schema. `issues` lists `path: problem`. */
+  | 'decode'
+  /** A value points at something the file does not declare (a zone, host, network). */
+  | 'reference'
+  /** A consumer asked for a product, service, zone, host or pin nobody declared. */
+  | 'unknown-key'
+  /** The file was reviewed against a different `@homeflare/site` version. */
+  | 'derive-version'
+  /** A non-live site was asked to plan stage `live`. */
+  | 'stage'
+  /** The observed vault or account is not the one the site describes. */
+  | 'identity'
+  /** The file could not be located, read or parsed. */
+  | 'load'
+  /** The file is not committed on `main` and `siteDev` was not set. */
+  | 'checkout'
+  /** An environment override was refused. */
+  | 'override';
+
+export class SiteError extends Error {
+  override readonly name = 'SiteError';
+  readonly code: SiteErrorCode;
+  /** One line per problem, each naming its path. Empty when the message says it all. */
+  readonly issues: readonly string[];
+
+  constructor(code: SiteErrorCode, message: string, issues: readonly string[] = []) {
+    super(issues.length === 0 ? message : `${message}\n  ${issues.join('\n  ')}`);
+    this.code = code;
+    this.issues = issues;
+  }
+}
+
+/** Throw `unknown-key`, listing what IS declared so the fix is one glance away. */
+export function unknownKey(kind: string, key: string, declared: Iterable<string>): never {
+  const known = [...declared].sort();
+  const list = known.length === 0 ? 'none are declared' : `declared: ${known.join(', ')}`;
+  throw new SiteError('unknown-key', `unknown ${kind} "${key}" (${list})`);
+}
+
+/**
+ * Look a key up in a record, or throw `unknown-key`.
+ * ⛔ No fallback, ever. A plausible default host is how a typo becomes a live DNS record.
+ */
+export function lookup<V>(kind: string, record: Readonly<Record<string, V>>, key: string): V {
+  if (!Object.hasOwn(record, key)) unknownKey(kind, key, Object.keys(record));
+  return record[key] as V;
+}

package/src/guards.ts

@@ -0,0 +1,42 @@
+/**
+ * Guards that refuse a plan before it can touch the wrong thing.
+ *
+ * ⛔ EACH ONE FAILS CLOSED. A guard that warns is a guard nobody reads in a CI log.
+ */
+import { SiteError } from './errors.ts';
+import type { Site } from './schema.ts';
+
+/**
+ * Refuse a site reviewed against a different `@homeflare/site` than the one installed.
+ *
+ * ★ WHY EXACT EQUALITY. Derive rules are this package's behaviour. If a new version builds
+ *   one hostname differently, every repo on it would plan a rename — a REPLACE — without
+ *   anyone having looked. Holding `deriveVersion` equal to the installed version makes that
+ *   a deliberate, reviewed one-line bump in the site file instead.
+ */
+export function checkDeriveVersion(site: Site, installed: string): void {
+  if (site.deriveVersion === installed) return;
+  throw new SiteError(
+    'derive-version',
+    `the site file was reviewed against @homeflare/site ${site.deriveVersion}, ` +
+      `but ${installed} is installed. Read the CHANGELOG between them for derive changes, ` +
+      `then set "deriveVersion": "${installed}" — or install ${site.deriveVersion}.`,
+  );
+}
+
+/** Stages as a deploy tool names them. Only `live` is special here. */
+export type Stage = string;
+
+/**
+ * ⛔ STAGE `live` ONLY WITH A LIVE SITE. An example or testing site can never plan
+ *   against live state — its account ids and cluster name are placeholders, and a plan
+ *   against real state would read every live object as "not declared: delete".
+ */
+export function assertStage(site: Site, stage: Stage): void {
+  if (stage !== 'live' || site.kind === 'live') return;
+  throw new SiteError(
+    'stage',
+    `stage "live" needs a live site; this one is kind "${site.kind}". ` +
+      `Point HF_SITE_FILE at the live site file, or plan a non-live stage.`,
+  );
+}

package/src/identity.ts

@@ -0,0 +1,93 @@
+/**
+ * Compare the identity a site EXPECTS with the identity a live system REPORTS.
+ *
+ * ⛔ WHY EVERY LIVE PLAN CALLS THIS. An exported `BAO_ADDR` from another shell points a
+ *   stack at a different vault with nothing else looking wrong: the token works, the
+ *   mounts exist, and the plan reads that vault's objects as drift to "fix". Only the
+ *   vault's own `cluster_name` (from `sys/health`) and the Cloudflare account id say which
+ *   system is on the other end.
+ *
+ * ★ PURE. This module fetches nothing. The caller reads `sys/health` and the account with
+ *   its own client (the kit's OpenBao and Cloudflare resources already have one) and hands
+ *   the observed values in, so this runs anywhere and is trivial to test.
+ */
+import { SiteError, lookup } from './errors.ts';
+import type { Site } from './schema.ts';
+
+export interface Identity {
+  /** `cluster_name` from the vault's `sys/health`. */
+  readonly vaultClusterName?: string;
+  /** The namespace the client is using. `''` is the root namespace. */
+  readonly vaultNamespace?: string;
+  /** The Cloudflare account the credential resolves to. */
+  readonly cloudflareAccountId?: string;
+}
+
+export interface IdentityMismatch {
+  readonly field: keyof Identity;
+  readonly expected: string;
+  /** `undefined` when the caller did not observe it — which is itself a mismatch. */
+  readonly observed: string | undefined;
+}
+
+export interface ExpectedIdentityOptions {
+  /** The account alias the plan targets. Omit to leave the account out of the compare. */
+  readonly account?: string;
+}
+
+/** What the site says the live systems are. Throws `unknown-key` for an unknown alias. */
+export function expectedIdentity(site: Site, options: ExpectedIdentityOptions = {}): Identity {
+  const account =
+    options.account === undefined
+      ? undefined
+      : lookup('cloudflare account', site.cloudflare.accounts, options.account).id;
+  return {
+    vaultClusterName: site.vault.clusterName,
+    vaultNamespace: site.vault.namespace,
+    ...(account === undefined ? {} : { cloudflareAccountId: account }),
+  };
+}
+
+const FIELDS = ['vaultClusterName', 'vaultNamespace', 'cloudflareAccountId'] as const;
+
+/**
+ * Every field the expectation sets and the observation does not match.
+ * ⛔ An expected field the caller did not observe COUNTS AS A MISMATCH. "We did not check"
+ *   must never read the same as "it matched".
+ * ⛔ An expectation that sets NO field throws `identity`. Compared field by field, `{}`
+ *   matches every system there is, so a caller that built it by mistake (a wrong spread, a
+ *   renamed key) would pass the guard on any vault and any account.
+ */
+export function compareIdentity(
+  expected: Identity,
+  observed: Identity,
+): readonly IdentityMismatch[] {
+  if (FIELDS.every((field) => expected[field] === undefined)) {
+    throw new SiteError(
+      'identity',
+      'refusing to plan: the expected identity names no field, so it would match any system',
+    );
+  }
+  const mismatches: IdentityMismatch[] = [];
+  for (const field of FIELDS) {
+    const want = expected[field];
+    if (want === undefined) continue;
+    const got = observed[field];
+    if (got !== want) mismatches.push({ field, expected: want, observed: got });
+  }
+  return mismatches;
+}
+
+/** {@link compareIdentity}, throwing `identity` with one line per mismatch. */
+export function assertIdentity(expected: Identity, observed: Identity): void {
+  const mismatches = compareIdentity(expected, observed);
+  if (mismatches.length === 0) return;
+  throw new SiteError(
+    'identity',
+    'refusing to plan: the live system is not the one this site describes',
+    mismatches.map(
+      (m) =>
+        `${m.field}: expected "${m.expected}", observed ${m.observed === undefined ? 'nothing' : `"${m.observed}"`}`,
+    ),
+  );
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+/**
+ * @homeflare/site — one typed site config, and every name derived from it.
+ *
+ * ★ WHY. A public stack that types a hostname cannot be run by anyone else, and a stack
+ *   that re-derives a name its own way drifts from its siblings. Here the site file holds
+ *   the base values once; `derive()` builds every hostname, address and mount name the
+ *   same way in every repo; and names that must never follow a rule are PINNED.
+ *
+ *     import { decodeSite, derive } from '@homeflare/site';        // runtime-neutral
+ *     import { loadSite } from '@homeflare/site/load';              // Node / Bun: HF_SITE_FILE
+ *
+ * ⛔ RUNTIME-NEUTRAL. Nothing reachable from this file touches `node:*`, `bun:*`, the
+ *   filesystem or the environment. File and env reading live in `./load.ts`.
+ */
+export { VERSION } from './version.ts';
+export { SiteError, type SiteErrorCode } from './errors.ts';
+export { SITE_FORMAT, type Site, type SiteInput, SiteSchema } from './schema.ts';
+export { type ValidateOptions, decodeSite, validateSite } from './decode.ts';
+export {
+  type Derived,
+  type DerivedAccess,
+  type DerivedHost,
+  type DerivedVault,
+  derive,
+} from './derive.ts';
+export { type Pins, pins } from './pins.ts';
+export { inventory, pinnedPrincipalIssues, unknownPrincipals } from './inventory.ts';
+export { type Stage, assertStage, checkDeriveVersion } from './guards.ts';
+export {
+  type ExpectedIdentityOptions,
+  type Identity,
+  type IdentityMismatch,
+  assertIdentity,
+  compareIdentity,
+  expectedIdentity,
+} from './identity.ts';
+export {
+  SITE_TOKENS,
+  type SiteToken,
+  type ValuedToken,
+  renderTokens,
+  tokenValues,
+} from './tokens.ts';

package/src/inventory.ts

@@ -0,0 +1,55 @@
+/**
+ * The inventory: every name and address the site declares for a machine.
+ *
+ * ★ PINNED LISTS ARE CHECKED AGAINST IT, NOT GENERATED FROM IT. A principal list is a
+ *   subset of the inventory — an assertion a consumer's test makes — never a rendering of
+ *   it. The difference matters on the bad day: when a leg is renamed, a generated list
+ *   silently drops the old address, and the break-glass path goes with it (measured on
+ *   this estate 2026-08-12: "name is not a listed principal" on the only way in).
+ */
+import { joinPath } from './decode.ts';
+import { derive } from './derive.ts';
+import type { Site } from './schema.ts';
+
+/** Apex, zones, the vault's names, and every host key, alias, FQDN and leg address. */
+export function inventory(site: Site): ReadonlySet<string> {
+  const derived = derive(site);
+  const names = new Set<string>([
+    site.apex,
+    ...Object.values(derived.zones),
+    derived.vault.host,
+    derived.vault.apiHost,
+    site.vault.meshAddress,
+  ]);
+  for (const [key, host] of Object.entries(site.hosts)) {
+    names.add(key);
+    for (const alias of host.aliases ?? []) names.add(alias);
+    const built = derived.hosts[key];
+    if (built?.fqdn !== undefined) names.add(built.fqdn);
+    for (const address of Object.values(built?.addresses ?? {})) names.add(address);
+  }
+  return names;
+}
+
+/** The entries of `list` the inventory does not know. Empty means `list` is a subset. */
+export function unknownPrincipals(site: Site, list: readonly string[]): readonly string[] {
+  const known = inventory(site);
+  return list.filter((entry) => !known.has(entry));
+}
+
+/**
+ * Every pinned SSH principal the inventory does not know, as `path: entry` lines.
+ * ⚠️ A consumer TEST calls this; loading does not. A stale principal is a finding to fix
+ *   in review, not a reason to refuse a break-glass plan at 3am.
+ */
+export function pinnedPrincipalIssues(site: Site): readonly string[] {
+  const issues: string[] = [];
+  for (const [key, list] of Object.entries(site.pinned.sshPrincipals)) {
+    for (const entry of unknownPrincipals(site, list)) {
+      // ★ Bracketed like decode errors: `ssh-host.host` is one key, not two levels.
+      const path = joinPath(['pinned', 'sshPrincipals', key]);
+      issues.push(`${path}: "${entry}" is not in the inventory`);
+    }
+  }
+  return issues;
+}

package/src/load.ts

@@ -0,0 +1,186 @@
+/**
+ * `@homeflare/site/load` — read the site file named by `HF_SITE_FILE`.
+ *
+ * ⛔ NODE / BUN ONLY: this subpath reads a file and spawns git. Workers use `decodeSite`
+ *   from the main entry with JSON they already hold.
+ *
+ * ⛔ NO DEFAULT PATH, AND NO DEFAULT SITE. A missing `HF_SITE_FILE` refuses, naming the
+ *   example. A fallback would plan someone's stack against whatever file happened to be
+ *   there — or against the example's placeholder account.
+ *
+ * ★ PLAIN JSON, not JSONC: Nix, jq and Python read the same file, and none of them read
+ *   comments.
+ */
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import * as Cause from 'effect/Cause';
+import * as Config from 'effect/Config';
+import * as ConfigProvider from 'effect/ConfigProvider';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Schema from 'effect/Schema';
+import { checkoutProblem, readCheckout } from './checkout.ts';
+import { decodeStrict, formatIssues, validateSite } from './decode.ts';
+import { SiteError } from './errors.ts';
+import { ENV_OVERRIDES, GUARD_FIELDS, SITE_FILE_VAR, pickOverrides } from './overrides.ts';
+import { type Site, SiteSchema } from './schema.ts';
+
+export { ENV_OVERRIDES, SITE_FILE_VAR } from './overrides.ts';
+export { type CheckoutState, checkoutProblem, readCheckout } from './checkout.ts';
+
+/** Where the refusal points people. Shipped in the tarball and exported by path. */
+export const SITE_EXAMPLE = 'node_modules/@homeflare/site/site.example.json';
+
+export interface LoadSiteOptions {
+  /** Defaults to `process.env`. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  /** Resolves a relative `HF_SITE_FILE`. Defaults to `process.cwd()`. */
+  readonly cwd?: string;
+  /**
+   * Skip the committed-on-`main` check and accept `HF_SITE_*` overrides — what a
+   * consumer's `--site-dev` flag sets. Without it, any accepted override refuses.
+   */
+  readonly siteDev?: boolean;
+  /** The branch a reviewed site file lives on. Defaults to `main`. */
+  readonly branch?: string;
+  /** Test hook for the derive-version refusal. Defaults to the installed version. */
+  readonly installed?: string;
+}
+
+export interface LoadedSite {
+  readonly site: Site;
+  /** The absolute path that was read. */
+  readonly file: string;
+  /** Which `HF_SITE_*` overrides changed the file's values. Print these; they are silent otherwise. */
+  readonly overrides: readonly string[];
+}
+
+const SiteConfig = Config.schema(SiteSchema, 'site');
+
+/**
+ * ⚠️ `nested('hf')` MUST COME BEFORE `constantCase`. Measured 2026-09-21 on effect
+ *   4.0.0-rc.115: each transformation sees the path the previous one produced, so the
+ *   other order upper-cases `site.apex` to `SITE_APEX` and THEN prefixes a lower-case
+ *   `hf` — the provider looks for `hf_SITE_APEX`, finds nothing, and the file's value
+ *   wins. `HF_SITE_APEX` is ignored with no error at all. tests/load.test.ts measures both.
+ */
+function envProvider(accepted: Readonly<Record<string, string>>): ConfigProvider.ConfigProvider {
+  return ConfigProvider.fromEnv({ env: accepted }).pipe(
+    ConfigProvider.nested('hf'),
+    ConfigProvider.constantCase,
+  );
+}
+
+function withOverrides(json: unknown, accepted: Readonly<Record<string, string>>): Site {
+  const provider = ConfigProvider.orElse(
+    envProvider(accepted),
+    ConfigProvider.fromUnknown({ site: json }),
+  );
+  const exit = Effect.runSyncExit(SiteConfig.parse(provider));
+  if (Exit.isSuccess(exit)) return exit.value;
+  const error = Cause.squash(exit.cause);
+  const cause =
+    typeof error === 'object' && error !== null && 'cause' in error ? error.cause : error;
+  if (Schema.isSchemaError(cause)) {
+    throw new SiteError(
+      'override',
+      'an HF_SITE_* override is not a valid value',
+      formatIssues(cause.issue, 'site').map(nameTheVariable),
+    );
+  }
+  throw error;
+}
+
+/** `vault.port: …` → `HF_SITE_VAULT_PORT (vault.port): …`, so the fix names what to unset. */
+function nameTheVariable(issue: string): string {
+  for (const [name, path] of Object.entries(ENV_OVERRIDES)) {
+    const dotted = path.join('.');
+    if (issue.startsWith(`${dotted}: `)) return `${name} (${issue}`.replace(': ', '): ');
+  }
+  return issue;
+}
+
+async function readJson(file: string): Promise<unknown> {
+  let text: string;
+  try {
+    text = await readFile(file, 'utf8');
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new SiteError(
+      'load',
+      `${SITE_FILE_VAR} points at ${file}, which cannot be read: ${reason}`,
+    );
+  }
+  try {
+    return JSON.parse(text) as unknown;
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new SiteError(
+      'load',
+      `${file} is not plain JSON (${reason}). Site files carry no comments and no trailing commas.`,
+    );
+  }
+}
+
+/**
+ * Locate, check, read, decode and validate the site file.
+ * Throws {@link SiteError}: `load`, `checkout`, `override`, `decode`, `reference`,
+ * `derive-version`.
+ */
+export async function loadSite(options: LoadSiteOptions = {}): Promise<LoadedSite> {
+  const env = options.env ?? process.env;
+  const named = env[SITE_FILE_VAR]?.trim();
+  if (named === undefined || named === '') {
+    throw new SiteError(
+      'load',
+      `${SITE_FILE_VAR} is not set, and there is no default path. Start from the example: ` +
+        `copy ${SITE_EXAMPLE}, replace every value, then export ${SITE_FILE_VAR}=<that file>.`,
+    );
+  }
+  const file = resolve(options.cwd ?? process.cwd(), named);
+  // ★ Read before the checkout check, so a mistyped path says "cannot be read" rather
+  //   than "not committed" about a file that does not exist.
+  const json = await readJson(file);
+
+  if (options.siteDev !== true) {
+    const branch = options.branch ?? 'main';
+    const problem = checkoutProblem(await readCheckout(file), branch);
+    if (problem !== undefined) {
+      throw new SiteError(
+        'checkout',
+        `refusing ${file}: ${problem}. Live values come from a reviewed "${branch}"; ` +
+          `pass --site-dev (siteDev: true) to load it anyway.`,
+      );
+    }
+  }
+
+  // ★ The file is decoded ALONE first, strictly, so its own errors name file paths and a
+  //   misspelt key is refused before any override can paper over it.
+  const fromFile = decodeStrict(json);
+
+  const { accepted, refused } = pickOverrides(env);
+  if (refused.length > 0) {
+    throw new SiteError(
+      'override',
+      'unsupported HF_SITE_* variables; edit the site file instead',
+      refused.map(
+        (name) =>
+          `${name}: not in ENV_OVERRIDES — records, lists and guard fields ` +
+          `(${GUARD_FIELDS.join(', ')}) are never overridable`,
+      ),
+    );
+  }
+  const names = Object.keys(accepted);
+  // ⛔ An override is an unreviewed value: same switch as the checkout guard (overrides.ts).
+  if (names.length > 0 && options.siteDev !== true) {
+    throw new SiteError(
+      'override',
+      'HF_SITE_* overrides change reviewed values, so they need --site-dev (siteDev: true); ' +
+        'unset them, or edit the site file on a branch',
+      names,
+    );
+  }
+  const site = names.length === 0 ? fromFile : withOverrides(json, accepted);
+
+  return { site: validateSite(site, options), file, overrides: names };
+}

package/src/net.ts

@@ -0,0 +1,29 @@
+/**
+ * IPv4 arithmetic for leg addresses: a network's base plus a host number.
+ *
+ * ★ WHY A HOST NUMBER AND NOT A LAST OCTET. On a /24 they are the same thing, and that is
+ *   the common case. On a /23 or a /16 a "last octet" is ambiguous, while "the 11th
+ *   address after the network address" is not. The /24 reading stays exact.
+ */
+import { parseCidr } from './primitives.ts';
+
+function dotted(value: number): string {
+  return [24, 16, 8, 0].map((shift) => Math.floor(value / 2 ** shift) % 256).join('.');
+}
+
+/** The largest usable host number on a network (the broadcast address is excluded). */
+export function lastHostNumber(cidr: string): number {
+  const parsed = parseCidr(cidr);
+  if (parsed === undefined) throw new Error(`not an IPv4 network: ${cidr}`);
+  return 2 ** (32 - parsed.prefix) - 2;
+}
+
+/** `addressOn('192.0.2.0/24', 11)` is `192.0.2.11`. */
+export function addressOn(cidr: string, hostNumber: number): string {
+  const parsed = parseCidr(cidr);
+  if (parsed === undefined) throw new Error(`not an IPv4 network: ${cidr}`);
+  if (hostNumber < 1 || hostNumber > lastHostNumber(cidr)) {
+    throw new Error(`host number ${hostNumber} does not fit ${cidr}`);
+  }
+  return dotted(parsed.base + hostNumber);
+}

package/src/overrides.ts

@@ -0,0 +1,79 @@
+/**
+ * The environment variables `loadSite` accepts as overrides — and the ONLY ones.
+ *
+ * ★ WHY A LIST AND NOT "ANY HF_SITE_*". Effect's env provider will happily answer any
+ *   path, and three of the answers are wrong without an error. Measured 2026-09-21 on
+ *   effect 4.0.0-rc.115, overriding on top of the file via `ConfigProvider.orElse`:
+ *   1. A RECORD or ARRAY is REPLACED, not merged. `HF_SITE_NETWORKS_MGMT` decoded
+ *      `networks` as `{ "MGMT": … }` — every other network gone, and the key upper-cased.
+ *      `HF_SITE_ZONES_MGMT` did the same to `zones`, and `…_LIST_0` truncated a list.
+ *   2. A name that is another's name plus `_…` SHADOWS it. With `HF_SITE_LABELS_VAULT_API`
+ *      set, `labels.vault` was read as a record (every `HF_SITE_LABELS_VAULT_*` var) and
+ *      the decode failed "Expected string". Hence `vault.label` / `vault.apiLabel`.
+ *   3. The ORDER of `nested` and `constantCase` decides the prefix: see load.ts.
+ *   So only scalar leaves under plain structs are listed, and tests/overrides.test.ts
+ *   proves each one changes exactly its own path and nothing else.
+ *
+ * ⛔ GUARD FIELDS ARE NEVER OVERRIDABLE: `version`, `deriveVersion`, `kind`,
+ *   `vault.clusterName` and `vault.namespace`. An exported `HF_SITE_KIND=live` would defeat
+ *   the stage guard, and an overridden cluster name or namespace would make the identity
+ *   check compare against itself: a client that takes its namespace from the site would
+ *   switch namespace AND expectation together, and plan into the other one "matching".
+ *
+ * ⛔ AND OVERRIDES ARE DEV-ONLY. An override is an unreviewed value, exactly like an
+ *   uncommitted edit to the file, so `loadSite` accepts one only with `siteDev` — the same
+ *   switch as the checkout guard. A stray `HF_SITE_APEX` left in a shell would otherwise
+ *   plan a rename of every derived hostname against live state.
+ *
+ * ⚠️ `HF_` IS ALSO HUGGING FACE'S PREFIX (`HF_TOKEN`, `HF_HOME`). Only `HF_SITE_*` is read,
+ *   and only the names below ever reach the provider.
+ */
+
+/** Env var → the site path it overrides. */
+export const ENV_OVERRIDES: Readonly<Record<string, readonly string[]>> = {
+  HF_SITE_APEX: ['apex'],
+  HF_SITE_VAULT_LABEL: ['vault', 'label'],
+  HF_SITE_VAULT_API_LABEL: ['vault', 'apiLabel'],
+  HF_SITE_VAULT_PORT: ['vault', 'port'],
+  HF_SITE_VAULT_MESH_ADDRESS: ['vault', 'meshAddress'],
+  HF_SITE_VAULT_OIDC_MOUNT: ['vault', 'oidcMount'],
+  HF_SITE_VAULT_CLI_CALLBACK_PORT: ['vault', 'cliCallbackPort'],
+  HF_SITE_VAULT_LAN_HOST: ['vault', 'lan', 'host'],
+  HF_SITE_VAULT_LAN_PORT: ['vault', 'lan', 'port'],
+  HF_SITE_VAULT_LAN_SCHEME: ['vault', 'lan', 'scheme'],
+  HF_SITE_CLOUDFLARE_ACCESS_TEAM: ['cloudflare', 'access', 'team'],
+  HF_SITE_GITHUB_OWNER: ['github', 'owner'],
+  HF_SITE_PATHS_ESTATE_ROOT: ['paths', 'estateRoot'],
+};
+
+/** Site paths no variable may ever set. `tests/overrides.test.ts` holds the list to this. */
+export const GUARD_FIELDS: readonly string[] = [
+  'version',
+  'deriveVersion',
+  'kind',
+  'vault.clusterName',
+  'vault.namespace',
+];
+
+/** Locates the file; read by `loadSite`, never passed to the provider. */
+export const SITE_FILE_VAR = 'HF_SITE_FILE';
+
+const PREFIX = 'HF_SITE_';
+
+/**
+ * The accepted overrides present in `env`, or a refusal naming every rejected variable.
+ * Returns the names sorted, so a caller can print exactly what changed the file's values.
+ */
+export function pickOverrides(env: Readonly<Record<string, string | undefined>>): {
+  readonly accepted: Readonly<Record<string, string>>;
+  readonly refused: readonly string[];
+} {
+  const accepted: Record<string, string> = {};
+  const refused: string[] = [];
+  for (const [name, value] of Object.entries(env).sort(([a], [b]) => a.localeCompare(b))) {
+    if (!name.startsWith(PREFIX) || name === SITE_FILE_VAR || value === undefined) continue;
+    if (Object.hasOwn(ENV_OVERRIDES, name)) accepted[name] = value;
+    else refused.push(name);
+  }
+  return { accepted, refused };
+}

package/src/pins.ts

@@ -0,0 +1,40 @@
+/**
+ * Read PINNED values by key. Nothing here is computed; it only refuses unknown keys.
+ *
+ * ⛔ WHY THESE ARE NOT DERIVED — each is a replace or an outage if it ever follows a rule:
+ *   - `names`: Workers, D1, KV, R2 and Durable Object names follow no rule, and a derived
+ *     D1 name REPLACES the database, deleting its data.
+ *   - `certificates`: hostnames on an adopted certificate. A change reissues it and revokes
+ *     the one a host is still serving.
+ *   - `adopted`: ids and names of objects that already exist (an LB pool, a WAF ruleset,
+ *     Ceph and PBS names, PKI common names). Rendering one from a rule means a new object.
+ *   - `policies` and `sshPrincipals`: explicit lists. A break-glass principal must never
+ *     vanish because a network leg was renamed; `unknownPrincipals` checks them against
+ *     the inventory instead of generating them from it.
+ */
+import { lookup } from './errors.ts';
+import type { Site } from './schema.ts';
+
+export interface Pins {
+  /** A physical resource name, e.g. `pins.name('alerts.d1')`. */
+  name(key: string): string;
+  /** The hostnames on an adopted certificate. */
+  certificate(key: string): readonly string[];
+  /** An adopted object's id or name. */
+  adopted(key: string): string;
+  /** A policy list (emails, groups, CIDRs — whatever the enforcing repo reads). */
+  policy(key: string): readonly string[];
+  /** An SSH principal list. */
+  principals(key: string): readonly string[];
+}
+
+export function pins(site: Site): Pins {
+  const { pinned } = site;
+  return {
+    name: (key) => lookup('pinned name', pinned.names, key),
+    certificate: (key) => lookup('pinned certificate', pinned.certificates, key),
+    adopted: (key) => lookup('adopted id', pinned.adopted, key),
+    policy: (key) => lookup('pinned policy list', pinned.policies, key),
+    principals: (key) => lookup('pinned principal list', pinned.sshPrincipals, key),
+  };
+}