@specific.dev/spectest 0.38.0 → 0.41.0

package/src/harness/file-mounts.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  assertAbsolute,
+  certificateHostnames,
+  defaultKeyMode,
+  expandServiceToken,
+  isNoopChown,
+  mountFlag,
+  needsIdTables,
+  numericId,
+  resolveChownIds,
+} from "./file-mounts";
+
+describe("expandServiceToken", () => {
+  /** A component can't know the key a user will mount it under, so it
+   *  writes the token and we fill in the chosen name. */
+  test("substitutes the service's map key", () => {
+    expect(expandServiceToken("mirror: {{SPECTEST_SERVICE}}.internal:5000", "cluster")).toBe(
+      "mirror: cluster.internal:5000",
+    );
+  });
+
+  test("substitutes every occurrence, not just the first", () => {
+    expect(expandServiceToken("{{SPECTEST_SERVICE}}/{{SPECTEST_SERVICE}}", "k3s")).toBe(
+      "k3s/k3s",
+    );
+  });
+
+  test("leaves content without the token untouched", () => {
+    expect(expandServiceToken("plain: true", "k3s")).toBe("plain: true");
+  });
+});
+
+describe("numericId", () => {
+  test("reads a numeric id as itself", () => {
+    expect(numericId("1000")).toBe(1000);
+    expect(numericId("0")).toBe(0);
+  });
+
+  test("a name is not an id", () => {
+    expect(numericId("postgres")).toBeUndefined();
+  });
+
+  /** Anything non-numeric must fall through to the image's tables rather
+   *  than being coerced — `Number("12a")` is NaN, and a NaN uid would
+   *  reach the syscall. */
+  test("a partly numeric value is a name, not an id", () => {
+    expect(numericId("12a")).toBeUndefined();
+    expect(numericId("")).toBeUndefined();
+  });
+
+  test("absent stays absent", () => {
+    expect(numericId(undefined)).toBeUndefined();
+  });
+});
+
+describe("needsIdTables", () => {
+  /** Probing an image costs a docker create + cp, so two numeric ids
+   *  should skip it entirely. */
+  test("numeric ids need no image probe", () => {
+    expect(needsIdTables("1000", "1000")).toBe(false);
+  });
+
+  test("naming nobody needs no probe", () => {
+    expect(needsIdTables(undefined, undefined)).toBe(false);
+  });
+
+  test("a name on either side needs the tables", () => {
+    expect(needsIdTables("postgres", undefined)).toBe(true);
+    expect(needsIdTables(undefined, "postgres")).toBe(true);
+    expect(needsIdTables("1000", "ssl-cert")).toBe(true);
+  });
+});
+
+describe("defaultKeyMode", () => {
+  test("an explicit mode always wins", () => {
+    expect(defaultKeyMode("0644", { uid: 70, gid: 70 })).toBe("0644");
+    expect(defaultKeyMode("0644", undefined)).toBe("0644");
+  });
+
+  /** Reached only when an owner was named, so no environment that never
+   *  mentioned ownership changes behaviour. */
+  test("no owner means no default, leaving existing environments alone", () => {
+    expect(defaultKeyMode(undefined, undefined)).toBeUndefined();
+  });
+
+  test("naming a user gives the strictest mode that user can open", () => {
+    expect(defaultKeyMode(undefined, { uid: 70, gid: -1 })).toBe("0600");
+    expect(defaultKeyMode(undefined, { uid: 70, gid: 70 })).toBe("0600");
+  });
+
+  /** With only a group named, 0600 would lock out the very reader that
+   *  was just declared. */
+  test("naming only a group keeps the group able to read", () => {
+    expect(defaultKeyMode(undefined, { uid: -1, gid: 101 })).toBe("0640");
+  });
+});
+
+describe("resolveChownIds", () => {
+  /** The landmine: Bun's fs.chown rejects -1 with EPERM where chown(2)
+   *  and node both read it as "leave this one alone". Passing it straight
+   *  through breaks exactly the common cases — a user with no group, and
+   *  the reverse. */
+  test("an unchanged half is filled from the file's current owner", () => {
+    expect(resolveChownIds({ uid: 70, gid: -1 }, { uid: 0, gid: 0 })).toEqual({
+      uid: 70,
+      gid: 0,
+    });
+    expect(resolveChownIds({ uid: -1, gid: 101 }, { uid: 0, gid: 0 })).toEqual({
+      uid: 0,
+      gid: 101,
+    });
+  });
+
+  test("both halves specified are passed through", () => {
+    expect(resolveChownIds({ uid: 70, gid: 101 }, { uid: 0, gid: 0 })).toEqual({
+      uid: 70,
+      gid: 101,
+    });
+  });
+
+  test("uid 0 is a real owner, not an absent one", () => {
+    expect(resolveChownIds({ uid: 0, gid: 0 }, { uid: 70, gid: 70 })).toEqual({
+      uid: 0,
+      gid: 0,
+    });
+  });
+
+  test("neither half specified resolves to the current owner", () => {
+    expect(resolveChownIds({ uid: -1, gid: -1 }, { uid: 5, gid: 6 })).toEqual({
+      uid: 5,
+      gid: 6,
+    });
+  });
+});
+
+describe("isNoopChown", () => {
+  test("recognises an owner that asks for nothing", () => {
+    expect(isNoopChown({ uid: -1, gid: -1 })).toBe(true);
+  });
+
+  test("any named half is not a no-op", () => {
+    expect(isNoopChown({ uid: 0, gid: -1 })).toBe(false);
+    expect(isNoopChown({ uid: -1, gid: 0 })).toBe(false);
+  });
+});
+
+describe("assertAbsolute", () => {
+  test("accepts an absolute path", () => {
+    expect(() => assertAbsolute("db", "file path", "/etc/postgresql/server.crt")).not.toThrow();
+  });
+
+  /** Docker would resolve a relative path against the image's working
+   *  directory, so the file would land somewhere the project never said. */
+  test("refuses a relative path, naming the service and the field", () => {
+    expect(() => assertAbsolute("db", "certificate keyPath", "certs/server.key")).toThrow(
+      /service "db": certificate keyPath "certs\/server.key" must be absolute/,
+    );
+  });
+});
+
+describe("certificateHostnames", () => {
+  test("expands the service token in SANs", () => {
+    expect(certificateHostnames("api", 0, ["{{SPECTEST_SERVICE}}.internal"])).toEqual([
+      "api.internal",
+    ]);
+  });
+
+  /** A certificate with no SANs verifies against nothing; failing at
+   *  mint time says so, where a TLS error at request time would not. */
+  test("refuses an entry with no hostnames", () => {
+    expect(() => certificateHostnames("api", 2, [])).toThrow(
+      /certificate entry 2 lists no hostnames/,
+    );
+  });
+});
+
+describe("mountFlag", () => {
+  test("mounts read-only", () => {
+    expect(mountFlag("/workspace/.spectest/files/db/x", "/etc/x.conf")).toBe(
+      "--volume=/workspace/.spectest/files/db/x:/etc/x.conf:ro",
+    );
+  });
+});

package/src/harness/file-mounts.ts

@@ -0,0 +1,145 @@
+/**
+ * Staging `files` and `certificates` for bind-mounting into a container.
+ *
+ * Ported out of `daemon.ts` as part of the harness split. These are the
+ * *pre-entrypoint* injection point — the only way to put something in place
+ * before the container's own process starts, which is what a config file a
+ * daemon reads at startup, or a TLS key it refuses to run without, actually
+ * needs. `setup` and `helpers` both run too late.
+ *
+ * What lives here is the part that decides *what* is staged and with which
+ * permissions. Writing the bytes, minting the certificate and running chown
+ * stay with the caller — but every rule that has ever been reported as a bug
+ * is a pure function below, with a test.
+ *
+ * ## The permission rules, and why they are not obvious
+ *
+ * **A bind mount carries the host inode's mode and ownership straight
+ * through, and the harness writes as root.** So `mode` on its own is not
+ * enough: locking a file down to `0600` gives the container a file owned by
+ * root that whoever it runs as cannot open. Postgres refusing to start on
+ * its own TLS key is the canonical report. `user`/`group` exist to name the
+ * reader, and naming one is what makes a strict mode usable.
+ *
+ * **Declaring a reader also implies the mode.** A key whose owner is named
+ * gets the strictest mode that owner can still open — `0600` when a user is
+ * named, `0640` when only a group is. A server that checks (postgres, ssh)
+ * refuses a lax key, so defaulting to something permissive would just move
+ * the failure. This only applies when an owner was named, so no existing
+ * environment changes behaviour.
+ *
+ * **`-1` means "leave this half alone", and Bun will not accept it.**
+ * chown(2) and node both read `-1` as unchanged, which is how plain `chown`
+ * lets you set a user without touching the group. Bun's `fs.chown` rejects
+ * it with `EPERM` (measured on Bun 1.3.14), so the untouched half has to be
+ * filled in from the file's current owner before the call —
+ * {@link resolveChownIds} is that, kept separate so the rule is testable
+ * without a filesystem.
+ */
+
+/** Numeric ids for a staged file. `-1` means "unchanged". */
+export interface OwnerIds {
+  uid: number;
+  gid: number;
+}
+
+/** `{{SPECTEST_SERVICE}}` → the service's map key.
+ *
+ *  Lets a component author self-referential config without knowing the key
+ *  the user will choose for it — k3s's `registries.yaml` pointing at
+ *  `<key>.internal:5000` is the reason this exists. */
+export function expandServiceToken(text: string, service: string): string {
+  return text.replaceAll("{{SPECTEST_SERVICE}}", service);
+}
+
+/** Parse a `user`/`group` value that may be a numeric id already. */
+export function numericId(value: string | undefined): number | undefined {
+  return value !== undefined && /^[0-9]+$/.test(value) ? Number(value) : undefined;
+}
+
+/**
+ * Does resolving this owner need the image's `/etc/passwd` + `/etc/group`?
+ *
+ * Probing an image costs a `docker create` + `docker cp`, so it is worth
+ * knowing that two numeric ids need no probe at all.
+ */
+export function needsIdTables(user?: string, group?: string): boolean {
+  return (
+    (user !== undefined && numericId(user) === undefined) ||
+    (group !== undefined && numericId(group) === undefined)
+  );
+}
+
+/**
+ * The mode a certificate's key should get.
+ *
+ * `undefined` when no owner was named — the file keeps whatever the harness
+ * wrote, which is the pre-existing behaviour for every environment that
+ * never asked about ownership.
+ */
+export function defaultKeyMode(
+  explicit: string | undefined,
+  owner: OwnerIds | undefined,
+): string | undefined {
+  if (explicit) return explicit;
+  if (!owner) return undefined;
+  // Only a group was named, so the group has to be able to read it.
+  return owner.uid === -1 ? "0640" : "0600";
+}
+
+/**
+ * Fill in the halves of a chown that were meant to be left alone.
+ *
+ * Takes the file's current ids rather than reading them, so the rule is a
+ * pure function. See the module header for why `-1` cannot simply be passed
+ * through under Bun.
+ */
+export function resolveChownIds(owner: OwnerIds, current: OwnerIds): OwnerIds {
+  return {
+    uid: owner.uid < 0 ? current.uid : owner.uid,
+    gid: owner.gid < 0 ? current.gid : owner.gid,
+  };
+}
+
+/** True when the owner asks for no change at all, so the chown can be
+ *  skipped entirely rather than resolved and re-applied. */
+export function isNoopChown(owner: OwnerIds): boolean {
+  return owner.uid < 0 && owner.gid < 0;
+}
+
+/**
+ * Reject a container path that isn't absolute.
+ *
+ * A relative path would be resolved by docker against the container's
+ * working directory, so the file would land somewhere that depends on the
+ * image rather than where the project said — a mount that appears to work
+ * and puts the file in the wrong place is worse than one that refuses.
+ */
+export function assertAbsolute(service: string, label: string, p: string): void {
+  if (!p.startsWith("/")) {
+    throw new Error(
+      `service ${JSON.stringify(service)}: ${label} ${JSON.stringify(p)} must be absolute`,
+    );
+  }
+}
+
+/** The hostnames a certificate entry covers, with the service token
+ *  expanded and the empty case refused. */
+export function certificateHostnames(
+  service: string,
+  index: number,
+  hostnames: readonly string[],
+): string[] {
+  const expanded = hostnames.map((h) => expandServiceToken(h, service));
+  if (expanded.length === 0) {
+    throw new Error(
+      `service ${JSON.stringify(service)}: certificate entry ${index} lists no hostnames`,
+    );
+  }
+  return expanded;
+}
+
+/** A read-only single-file bind mount. */
+export function mountFlag(hostPath: string, containerPath: string): string {
+  return `--volume=${hostPath}:${containerPath}:ro`;
+}

package/src/harness/hostmatch.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  certCovers,
+  hostWithoutPort,
+  isWildcard,
+  matchRoute,
+  wildcardCoversHost,
+  wildcardSuffix,
+} from "./hostmatch";
+
+describe("wildcard shape", () => {
+  test("only `*.suffix` counts as a wildcard", () => {
+    expect(isWildcard("*.example.com")).toBe(true);
+    expect(isWildcard("api.example.com")).toBe(false);
+    // A bare `*` has no suffix to anchor on and is not a supported form.
+    expect(isWildcard("*")).toBe(false);
+  });
+
+  test("the suffix keeps its leading dot, which is what anchors the match", () => {
+    expect(wildcardSuffix("*.example.com")).toBe(".example.com");
+  });
+});
+
+describe("certificate coverage — one label only (RFC 6125)", () => {
+  test("covers exactly one label", () => {
+    expect(wildcardCoversHost("*.example.com", "api.example.com")).toBe(true);
+  });
+
+  /** The rule the whole module exists to protect. Relaxing this to a plain
+   *  suffix test makes certCovers claim a deep name is already served, so
+   *  the runtime-TLS path skips minting the leaf it needs and the client
+   *  gets a certificate it rejects. */
+  test("does NOT cover a deeper name", () => {
+    expect(wildcardCoversHost("*.example.com", "a.b.example.com")).toBe(false);
+  });
+
+  test("does not cover the bare domain", () => {
+    expect(wildcardCoversHost("*.example.com", "example.com")).toBe(false);
+  });
+
+  test("does not cover an unrelated domain that merely ends similarly", () => {
+    // "notexample.com" ends with "example.com" but not with ".example.com".
+    expect(wildcardCoversHost("*.example.com", "notexample.com")).toBe(false);
+    expect(wildcardCoversHost("*.example.com", "evil-example.com")).toBe(false);
+  });
+
+  test("certCovers accepts an exact entry", () => {
+    expect(certCovers(["api.example.com"], "api.example.com")).toBe(true);
+    expect(certCovers(["api.example.com"], "other.example.com")).toBe(false);
+  });
+
+  test("certCovers accepts a wildcard entry for one label", () => {
+    expect(certCovers(["*.example.com"], "api.example.com")).toBe(true);
+    expect(certCovers(["*.example.com"], "a.b.example.com")).toBe(false);
+  });
+
+  test("certCovers finds a wildcard that is not the first entry", () => {
+    // Bun matches a wildcard serverName even when it isn't first in the
+    // tls array; our own lookup must not depend on ordering either.
+    const names = ["one.test", "two.test", "*.example.com"];
+    expect(certCovers(names, "api.example.com")).toBe(true);
+  });
+
+  test("no configured certs covers nothing", () => {
+    expect(certCovers([], "api.example.com")).toBe(false);
+  });
+});
+
+describe("route matching — exact first, then longest suffix", () => {
+  test("an exact route beats a wildcard that also matches", () => {
+    const routes = new Map([
+      ["*.example.com", "wild"],
+      ["api.example.com", "exact"],
+    ]);
+    expect(matchRoute(routes, "api.example.com")).toBe("exact");
+  });
+
+  test("the longest matching wildcard wins", () => {
+    const routes = new Map([
+      ["*.example.com", "short"],
+      ["*.eu.example.com", "long"],
+    ]);
+    expect(matchRoute(routes, "a.eu.example.com")).toBe("long");
+    expect(matchRoute(routes, "a.us.example.com")).toBe("short");
+  });
+
+  test("insertion order does not decide the winner", () => {
+    const a = new Map([
+      ["*.eu.example.com", "long"],
+      ["*.example.com", "short"],
+    ]);
+    const b = new Map([
+      ["*.example.com", "short"],
+      ["*.eu.example.com", "long"],
+    ]);
+    expect(matchRoute(a, "x.eu.example.com")).toBe("long");
+    expect(matchRoute(b, "x.eu.example.com")).toBe("long");
+  });
+
+  /** Unlike a certificate, a wildcard ROUTE matches any depth — this is the
+   *  deliberate asymmetry: such a host reverse-proxies over http but needs
+   *  its own cert for https. */
+  test("a wildcard route matches any depth of subdomain", () => {
+    const routes = new Map([["*.example.com", "wild"]]);
+    expect(matchRoute(routes, "a.b.c.example.com")).toBe("wild");
+    // …while the cert rule refuses the same name.
+    expect(certCovers(["*.example.com"], "a.b.c.example.com")).toBe(false);
+  });
+
+  test("no match yields undefined rather than an arbitrary route", () => {
+    const routes = new Map([["*.example.com", "wild"]]);
+    expect(matchRoute(routes, "elsewhere.test")).toBeUndefined();
+  });
+
+  test("a route stored as a falsy value is still returned", () => {
+    // `byHost.get()` returning 0 or "" must not be mistaken for a miss.
+    const routes = new Map<string, number>([["api.test", 0]]);
+    expect(matchRoute(routes, "api.test")).toBe(0);
+  });
+
+  test("the bare domain does not match its own wildcard", () => {
+    const routes = new Map([["*.example.com", "wild"]]);
+    expect(matchRoute(routes, "example.com")).toBeUndefined();
+  });
+});
+
+describe("Host header parsing", () => {
+  test("strips a port", () => {
+    expect(hostWithoutPort("api.example.com:8080")).toBe("api.example.com");
+  });
+
+  test("leaves a portless host alone", () => {
+    expect(hostWithoutPort("api.example.com")).toBe("api.example.com");
+  });
+
+  test("trims surrounding whitespace", () => {
+    expect(hostWithoutPort("  api.example.com:80 ")).toBe("api.example.com");
+  });
+
+  /** A naive split on the last ':' mangles IPv6 literals; the brackets are
+   *  what disambiguate address colons from the port separator. */
+  test("keeps an IPv6 literal intact", () => {
+    expect(hostWithoutPort("[::1]:8080")).toBe("[::1]");
+    expect(hostWithoutPort("[::1]")).toBe("[::1]");
+    expect(hostWithoutPort("[2001:db8::1]:443")).toBe("[2001:db8::1]");
+  });
+});

package/src/harness/hostmatch.ts

@@ -0,0 +1,109 @@
+/**
+ * Hostname matching for ingress: which route serves a request, and which
+ * certificate may serve a TLS handshake.
+ *
+ * Ported out of `daemon.ts` as part of the harness split. These are pure
+ * functions guarding two rules that are easy to state and easy to get
+ * subtly wrong, and until now they had no tests at all.
+ *
+ * ## The two rules
+ *
+ * **Precedence: exact first, then longest suffix.** A `*.example.com`
+ * route and an `api.example.com` route can both match `api.example.com`;
+ * the exact one wins. Among competing wildcards the longest suffix wins,
+ * so `*.eu.example.com` beats `*.example.com` for `a.eu.example.com`.
+ * The same ordering applies at all three layers — DNS in the resolver,
+ * routes here, and SNI in Bun's cert table.
+ *
+ * **Routes and certificates match differently, deliberately.** A wildcard
+ * *route* matches any depth of subdomain, but a wildcard *certificate*
+ * covers exactly one label — which is what RFC 6125 says and what every
+ * TLS client enforces. So `a.b.example.com` under `*.example.com` is
+ * reverse-proxied happily over http, and needs its own cert entry for
+ * https.
+ *
+ * That asymmetry is load-bearing, not an oversight. Loosening
+ * {@link wildcardCoversHost} to a plain suffix test would make
+ * {@link certCovers} report that a deep name is already covered, so the
+ * runtime-TLS path would skip minting the leaf that name actually needs
+ * and hand the client a certificate it rejects — a TLS failure at request
+ * time, far from the code that caused it.
+ */
+
+// Re-exported rather than redefined: `ingress.ts` owns the wildcard shape
+// for the declarative lowering, and two copies of "what counts as a
+// wildcard" is precisely the drift this port exists to remove.
+export { isWildcard } from "../ingress";
+import { isWildcard } from "../ingress";
+
+/** `"*.example.com"` → `".example.com"`. */
+export function wildcardSuffix(pattern: string): string {
+  return pattern.slice(1);
+}
+
+/**
+ * Does a wildcard *certificate* pattern cover `hostname`?
+ *
+ * One label only (RFC 6125): `*.example.com` covers `api.example.com` and
+ * NOT `a.b.example.com`. See the module header for why this must not be
+ * relaxed into a suffix test.
+ */
+export function wildcardCoversHost(pattern: string, hostname: string): boolean {
+  const suffix = wildcardSuffix(pattern);
+  if (!hostname.endsWith(suffix)) return false;
+  const label = hostname.slice(0, -suffix.length);
+  return label.length > 0 && !label.includes(".");
+}
+
+/**
+ * Is `hostname` already served by an exact or wildcard certificate?
+ *
+ * Takes the set of configured server names rather than reading module
+ * state, so the rule is testable on its own — the caller passes
+ * `HTTPS_CERT_BY_HOST.keys()`.
+ */
+export function certCovers(serverNames: Iterable<string>, hostname: string): boolean {
+  const names = [...serverNames];
+  if (names.includes(hostname)) return true;
+  return names.some((n) => isWildcard(n) && wildcardCoversHost(n, hostname));
+}
+
+/**
+ * Pick the route for `host`: exact match first, then the longest matching
+ * wildcard suffix.
+ *
+ * Unlike a certificate, a wildcard route matches any depth — `*.test`
+ * serves `a.b.test`.
+ */
+export function matchRoute<T>(byHost: ReadonlyMap<string, T>, host: string): T | undefined {
+  const exact = byHost.get(host);
+  if (exact !== undefined) return exact;
+  let best: T | undefined;
+  let bestLen = -1;
+  for (const [pattern, route] of byHost) {
+    if (!isWildcard(pattern)) continue;
+    const suffix = wildcardSuffix(pattern);
+    if (host.endsWith(suffix) && suffix.length > bestLen) {
+      best = route;
+      bestLen = suffix.length;
+    }
+  }
+  return best;
+}
+
+/**
+ * Strip the port from a `Host` header value.
+ *
+ * IPv6 literals arrive bracketed (`[::1]:8080`), so a naive split on the
+ * last `:` would mangle them; the brackets are what disambiguate.
+ */
+export function hostWithoutPort(hostHeader: string): string {
+  const h = hostHeader.trim();
+  if (h.startsWith("[")) {
+    const close = h.indexOf("]");
+    if (close !== -1) return h.slice(0, close + 1);
+    return h;
+  }
+  const colon = h.lastIndexOf(":");
+  return colon === -1 ? h : h.slice(0, colon);
+}