@caelo-cms/provisioning 0.10.52 → 0.10.55

package/src/self-hosted-upgrade.ts

@@ -13,9 +13,15 @@
  *      the same `migrate.ts` entrypoint the GCP migrate job runs) while the
  *      old containers keep serving — migrations are expand-only, so the
  *      running release works on the new schema;
- *   5. recreate the admin, health-check it (`/_caelo/health`, which proves
+ *   5. converge the database roles (the same script `cms-provision up`
+ *      runs): bootstrap.sh only runs on the data volume's first start, so a
+ *      role a release retires — #635's gateway_role — is dropped here, on
+ *      every existing install. After the migrations, because the runner
+ *      refuses an install that skipped the release the old role's last user
+ *      was retired in (run-order.ts): past it, nothing running uses it;
+ *   6. recreate the admin, health-check it (`/_caelo/health`, which proves
  *      the DB pool and roles); then the gateway (`/healthz`);
- *   6. record the release in `.caelo/release.json`.
+ *   7. record the release in `.caelo/release.json`.
  * Any failure after step 3 puts the previous Compose file back; once a
  * container was recreated the previous images are started again and
  * health-checked (rollback). The database is never restored automatically:
@@ -52,6 +58,7 @@ import {
   releaseImages,
   resolveVerifiedRelease,
 } from "./self-hosted-release.js";
+import type { ConvergeOutcome } from "./self-hosted-roles.js";
 import { fetchLatestReleaseTag, RELEASE_SERVICES, releaseTag } from "./upgrade/release-images.js";
 
 /** The Compose service names of the two Caelo services. */
@@ -78,6 +85,11 @@ export interface SelfHostedUpgradeDeps {
   /** Renders the Compose file for `images` from the install's config (secrets included). */
   readonly renderCompose: (images: ReleaseImages) => string;
   readonly log: UpgradeLog;
+  /**
+   * Converges the database roles as the Postgres superuser
+   * (`convergeSelfHostedRoles`); drops roles a release retired (#635).
+   */
+  readonly convergeRoles: () => Promise<ConvergeOutcome>;
   readonly fetchImpl?: typeof fetch;
   readonly sleep?: (ms: number) => Promise<void>;
   readonly now?: () => Date;
@@ -116,6 +128,7 @@ type UpgradeStage =
   | "backup"
   | "pull"
   | "migrate"
+  | "roles"
   | "roll-admin"
   | "roll-gateway";
 
@@ -321,7 +334,19 @@ export async function upgradeSelfHosted(
     );
   }
 
-  // 5. Roll admin, then gateway, each health-checked.
+  // 5. Database roles: drops what this release retired (#635 gateway_role).
+  log.step("Converging the database roles");
+  const roles = await deps.convergeRoles();
+  if (!roles.ok) {
+    restoreCompose(file, previousCompose);
+    return fail(
+      "roles",
+      `Could not converge the database roles: ${roles.error}\nThe previous release keeps running; the migrations are applied (expand-only). Fix the cause and re-run the upgrade. Database backup: ${backup.dir}`,
+      true,
+    );
+  }
+
+  // 6. Roll admin, then gateway, each health-checked.
   for (const service of RELEASE_SERVICES) {
     const stage = service === "admin" ? "roll-admin" : "roll-gateway";
     log.phase?.("roll");
@@ -353,7 +378,7 @@ export async function upgradeSelfHosted(
     log.info(`${service} healthy ✓`);
   }
 
-  // 6. Record.
+  // 7. Record.
   log.phase?.("record");
   recordRelease(
     caeloDir,

package/src/stack-contract.test.ts

@@ -74,6 +74,8 @@ describe("adminEnvContract", () => {
       CAELO_OPERATOR_ACCESS_JOB:
         "projects/acme/locations/europe-west1/jobs/caelo-production-operator-access-sync",
       CAELO_UPGRADER_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-upgrader",
+      CAELO_AUDIT_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-audit",
+      CAELO_AUDIT_RESULTS_BUCKET: "acme-caelo-production-audit-results",
       CAELO_STATIC_BUCKET: "acme-caelo-production-static",
       CAELO_STAGING_BUCKET: "acme-caelo-production-staging",
       ...ADMIN_SECRETS,
@@ -104,6 +106,8 @@ describe("adminEnvContract", () => {
       CAELO_OPERATOR_ACCESS_JOB:
         "projects/acme/locations/europe-west1/jobs/caelo-production-operator-access-sync",
       CAELO_UPGRADER_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-upgrader",
+      CAELO_AUDIT_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-audit",
+      CAELO_AUDIT_RESULTS_BUCKET: "acme-caelo-production-audit-results",
       CAELO_FIREBASE_SITE: "caelo-production-site-abc123",
       CAELO_GATEWAY_SERVICE: "caelo-production-gateway-1a2b3c4",
       CAELO_GATEWAY_REGION: "europe-west1",
@@ -158,12 +162,21 @@ describe("gatewayEnvContract", () => {
       CAELO_PROVIDER: "gcp",
       CAELO_ENV: "production",
       MEDIA_STORAGE_URL: "gs://acme-caelo-production-media",
+      // #845 — gcp: the LB appends <client>,<LB IP>.
+      CAELO_TRUSTED_PROXY_HOPS: "2",
       PUBLIC_DATABASE_URL: "postgresql://public_role@10.20.0.3:5432/cms_public?sslmode=require",
       PUBLIC_DATABASE_PASSWORD: "secret:caelo-production-public-role-password:latest",
       CAELO_STAGING_GATE_SECRET: "secret:caelo-production-staging-gate-secret:latest",
     });
   });
 
+  it("#845 — tells the gateway its provider's proxy hop count", () => {
+    // Firebase Hosting / the domain mapping: Cloud Run's front end only.
+    const fb = asRecord(gatewayEnvContract({ ...base, provider: "gcp-firebase" }));
+    expect(fb.CAELO_TRUSTED_PROXY_HOPS).toBe("1");
+    expect(asRecord(gateway).CAELO_TRUSTED_PROXY_HOPS).toBe("2");
+  });
+
   it("#650 — reads the staging host from the database, not its env", () => {
     const fb = asRecord(gatewayEnvContract({ ...base, provider: "gcp-firebase" }));
     expect(fb.CAELO_STAGING_HOST).toBeUndefined();
@@ -223,14 +236,13 @@ describe("database role secrets (#613)", () => {
     expect(DATABASE_ROLE_SECRET).toEqual({
       admin_role: "postgres-password",
       public_role: "public-role-password",
-      gateway_role: "gateway-role-password",
     });
   });
 
-  it("the CLI generates the gateway's role passwords (never seeded from admin_role's)", () => {
-    expect(CLI_GENERATED_SECRETS).toEqual(
-      expect.arrayContaining(["public-role-password", "gateway-role-password"]),
-    );
+  it("the CLI generates the gateway's role password (never seeded from admin_role's)", () => {
+    expect(CLI_GENERATED_SECRETS).toContain("public-role-password");
+    // #635 — the former gateway_role is gone; nothing generates its password.
+    expect(CLI_GENERATED_SECRETS as readonly string[]).not.toContain("gateway-role-password");
   });
 
   it("retires the gateway SA's read access to admin_role's password", () => {
@@ -287,11 +299,7 @@ describe("runtime secrets", () => {
   });
 
   it("every CLI-generated secret is read by some service", () => {
-    // gateway-role-password is read by no service since #635: it only keeps
-    // the legacy gateway_role's password set until the contract release
-    // drops the role (the previous release's gateway logs in with it while
-    // an upgrade rolls).
-    for (const s of CLI_GENERATED_SECRETS.filter((x) => x !== "gateway-role-password")) {
+    for (const s of CLI_GENERATED_SECRETS) {
       expect([...serviceSecrets("admin"), ...serviceSecrets("gateway")]).toContain(s);
     }
   });
@@ -302,7 +310,7 @@ describe("self-hosted compose", () => {
     const yaml = generateDockerCompose({
       domain: "acme.com",
       postgresPassword: "p",
-      rolePasswords: { admin: "a", public: "b", gateway: "g" },
+      rolePasswords: { admin: "a", public: "b" },
       caeloSecretKek: "k",
       diskSize: "10G",
       ports: { http: 80, https: 443 },

package/src/stack-contract.ts

@@ -34,7 +34,9 @@
  * Pure module — the stacks import it from `dist/`.
  */
 
+import type { SupportedProvider } from "./adapter.js";
 import {
+  auditJobResource,
   gatewayServiceAccountEmail,
   gcpBucketName,
   gcpNamePrefix,
@@ -168,6 +170,15 @@ export const OPERATOR_ACCESS_JOB_ENV_VAR = "CAELO_OPERATOR_ACCESS_JOB";
  */
 export const UPGRADER_JOB_ENV_VAR = "CAELO_UPGRADER_JOB";
 
+/**
+ * #875 — the admin env vars naming the parallel quality-audit job and the
+ * bucket its tasks write results into (admin-core quality/
+ * gcp-audit-launcher.ts). `upgrade` leaves them untouched when it could not
+ * set the job up.
+ */
+export const AUDIT_JOB_ENV_VAR = "CAELO_AUDIT_JOB";
+export const AUDIT_RESULTS_BUCKET_ENV_VAR = "CAELO_AUDIT_RESULTS_BUCKET";
+
 /** Where the admin image ships the static-generator CLI. */
 const GENERATOR_CLI = "/app/apps/static-generator/src/cli.ts";
 
@@ -237,14 +248,13 @@ export function adminMediaVolumeTemplate(volume: MediaVolumeContract) {
 export type RuntimeSecret =
   | "postgres-password"
   | "public-role-password"
-  | "gateway-role-password"
   | "secret-kek"
   | "internal-secret"
   | "tool-approval-secret"
   | "staging-gate-secret";
 
 /** The Postgres roles Caelo's services log in as, with their passwords. */
-export type DatabaseRole = "admin_role" | "public_role" | "gateway_role";
+export type DatabaseRole = "admin_role" | "public_role";
 
 /**
  * Each database role's password secret — one per role (#613), so the
@@ -256,7 +266,6 @@ export type DatabaseRole = "admin_role" | "public_role" | "gateway_role";
 export const DATABASE_ROLE_SECRET: Readonly<Record<DatabaseRole, RuntimeSecret>> = {
   admin_role: "postgres-password",
   public_role: "public-role-password",
-  gateway_role: "gateway-role-password",
 };
 
 /**
@@ -269,10 +278,9 @@ export const DATABASE_ROLE_SECRET: Readonly<Record<DatabaseRole, RuntimeSecret>>
 export const CLI_GENERATED_SECRETS = [
   "internal-secret",
   "tool-approval-secret",
-  // #613 — the gateway's own role passwords. Generated (never seeded from
+  // #613 — the gateway's own role password. Generated (never seeded from
   // `postgres-password`), so the gateway never learns admin_role's.
   "public-role-password",
-  "gateway-role-password",
   // #650 — the staging access gate's key: signs "Open staging" links and
   // session cookies, derives the crawler credentials. Read by the admin
   // (issues) and the gateway (verifies).
@@ -358,6 +366,42 @@ function commonEnv(inputs: ServiceEnvInputs): CloudRunEnvVar[] {
   ];
 }
 
+/**
+ * The env var telling the gateway which `X-Forwarded-For` entry is the
+ * visitor (apps/api-gateway client-ip.ts): the number of entries the proxies
+ * in front of it append, counting the client's own.
+ */
+export const TRUSTED_PROXY_HOPS_ENV = "CAELO_TRUSTED_PROXY_HOPS";
+
+/**
+ * {@link TRUSTED_PROXY_HOPS_ENV} per provider — a property of each
+ * adapter's topology (CLAUDE.md §11.B), so it is declared here once and every
+ * adapter sets it on its gateway. The gateway refuses to boot without it.
+ * A change to an adapter's path to the gateway must update its entry, or
+ * rate limits pool every visitor (too high) or trust a forgeable entry (too
+ * low).
+ */
+export const GATEWAY_TRUSTED_PROXY_HOPS: Readonly<Record<SupportedProvider, number>> = {
+  // External Application LB appends `<client>,<LB IP>`; the gateway's
+  // ingress is internal-and-LB only, so nothing reaches it around the LB.
+  gcp: 2,
+  // Cloud Run's front end appends its peer. Behind the Firebase Hosting
+  // rewrite that peer is the Hosting CDN edge, and the entry Hosting adds
+  // before it cannot be told apart from a forged one (the service is
+  // invokable on *.run.app too) — so the edge address is the most that can
+  // be trusted. Staging (Cloud Run domain mapping) gets the visitor.
+  "gcp-firebase": 1,
+  // Caddy without `trusted_proxies` replaces the header with its peer; the
+  // gateway is reachable only on the Compose network.
+  "self-hosted": 1,
+  // CloudFront appends the viewer, the ALB appends CloudFront. (No ECS task
+  // definition consumes it yet — see stacks/aws.)
+  aws: 2,
+  // Container Apps ingress appends its peer; the gateway's ingress is
+  // internal to the environment (no Front Door route to it yet).
+  azure: 1,
+};
+
 /**
  * The env of the gateway service. Order is stable so the stacks see no
  * spurious diffs.
@@ -365,6 +409,7 @@ function commonEnv(inputs: ServiceEnvInputs): CloudRunEnvVar[] {
 export function gatewayEnvContract<V>(inputs: RuntimeEnvInputs<V>): CloudRunEnvVar<V | string>[] {
   return [
     ...commonEnv(inputs),
+    { name: TRUSTED_PROXY_HOPS_ENV, value: String(GATEWAY_TRUSTED_PROXY_HOPS[inputs.provider]) },
     { name: "PUBLIC_DATABASE_URL", value: inputs.databaseUrls.public },
     ...secretEnv("gateway", inputs.env),
   ];
@@ -407,6 +452,10 @@ export function adminEnvContract<V>(inputs: AdminEnvInputs<V>): CloudRunEnvVar<V
     // #696 — the job "Install update" starts (upgrader-setup.ts); the admin
     // may only run it, never override it.
     { name: UPGRADER_JOB_ENV_VAR, value: upgraderJobResource(projectId, inputs.region, env) },
+    // #875 — the job the quality audit fans its Lighthouse runs out to, and
+    // where the tasks write their results (audit-job-setup.ts).
+    { name: AUDIT_JOB_ENV_VAR, value: auditJobResource(projectId, inputs.region, env) },
+    { name: AUDIT_RESULTS_BUCKET_ENV_VAR, value: gcpBucketName(projectId, env, "audit-results") },
   ];
   if (inputs.provider === "gcp") {
     // v0.2.78 — the GCS StaticPublisher: Stage uploads to staging,

package/src/stack-converge-secrets.test.ts

@@ -344,6 +344,8 @@ describe("upgrading a v0.10.35 install: the gateway leaves admin_role (#613)", (
       "ADMIN_DATABASE_URL",
       // #650 — the staging gate key arrives in the same roll.
       "CAELO_STAGING_GATE_SECRET",
+      // #845 — and which forwarded address is the visitor.
+      "CAELO_TRUSTED_PROXY_HOPS",
       "PUBLIC_DATABASE_PASSWORD",
     ]);
   });

package/src/stack-converge.test.ts

@@ -312,10 +312,12 @@ describe("planContractEnv", () => {
     // #650 — the same roll converges the protected staging domain's host
     // and gate key onto an install that predates it.
     expect(plan.services.admin.flags).toEqual([
-      "--update-env-vars=CAELO_SITE_URL=https://acme.com,MEDIA_ROOT_DIR=/app/apps/admin/data/media,CAELO_MCP_IAP_SERVICE_ACCOUNT=caelo-mcp@acme.iam.gserviceaccount.com,CAELO_OPERATOR_ACCESS_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-operator-access-sync,CAELO_UPGRADER_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-upgrader,CAELO_STAGING_HOST=staging.acme.com",
+      "--update-env-vars=CAELO_SITE_URL=https://acme.com,MEDIA_ROOT_DIR=/app/apps/admin/data/media,CAELO_MCP_IAP_SERVICE_ACCOUNT=caelo-mcp@acme.iam.gserviceaccount.com,CAELO_OPERATOR_ACCESS_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-operator-access-sync,CAELO_UPGRADER_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-upgrader,CAELO_AUDIT_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-audit,CAELO_AUDIT_RESULTS_BUCKET=acme-caelo-production-audit-results,CAELO_STAGING_HOST=staging.acme.com",
       "--update-secrets=CAELO_STAGING_GATE_SECRET=caelo-production-staging-gate-secret:latest",
     ]);
     expect(plan.services.gateway.flags).toEqual([
+      // The gateway learns which forwarded address is the visitor (#845).
+      "--update-env-vars=CAELO_TRUSTED_PROXY_HOPS=1",
       "--update-secrets=CAELO_STAGING_GATE_SECRET=caelo-production-staging-gate-secret:latest",
     ]);
   });

package/src/tar-entries.test.ts

@@ -35,18 +35,160 @@ describe("listTarEntries", () => {
   });
 
   it("refuses a truncated archive instead of skipping members", () => {
-    const header = new Uint8Array(512);
-    header.set(new TextEncoder().encode("a.txt"), 0);
-    header.set(new TextEncoder().encode("00000001000\0"), 124); // 512 bytes of data, none present
-    header[156] = "0".charCodeAt(0);
-    expect(() => listTarEntries(header)).toThrow(/truncated/);
+    expect(() => listTarEntries(header("a.txt", "0", { sizeField: 512 }))).toThrow(/truncated/);
+  });
+
+  it("rejects PAX global extended headers ('g')", () => {
+    const g = member("PaxHeader", "g", paxLine("path=/etc/passwd"));
+    expect(() => listTarEntries(concat(g, member("safe.txt", "0"), END))).toThrow(
+      /pax global extended header/,
+    );
+  });
+
+  it("refuses a member named by two pax headers — GNU tar keeps the last, bsdtar drops the second", () => {
+    // Both tars extract `../../evil` here (the second header carries no
+    // path); reading the first header's path would have checked `safe.txt`.
+    const archive = concat(
+      member("PaxHeader", "x", paxLine("path=srv/caelo/safe.txt")),
+      member("PaxHeader", "x", paxLine("mtime=1")),
+      member("../../evil", "0"),
+      END,
+    );
+    expect(() => listTarEntries(archive)).toThrow(/several extension headers \(xx\)/);
+  });
+
+  it("refuses a GNU long name next to a pax path, and two long names", () => {
+    // bsdtar extracts the `L` name (`../../evil`), GNU tar the pax path.
+    const mixed = concat(
+      member("././@LongLink", "L", "../../evil\0"),
+      member("PaxHeader", "x", paxLine("path=srv/caelo/safe.txt")),
+      member("x", "0"),
+      END,
+    );
+    expect(() => listTarEntries(mixed)).toThrow(/several extension headers \(Lx\)/);
+    const twice = concat(
+      member("././@LongLink", "L", "../../evil\0"),
+      member("././@LongLink", "L", "safe.txt\0"),
+      member("x", "0"),
+      END,
+    );
+    expect(() => listTarEntries(twice)).toThrow(/several extension headers \(LL\)/);
+  });
+
+  it("still reads a GNU long name together with a long link", () => {
+    const archive = concat(
+      member("././@LongLink", "K", "target\0"),
+      member("././@LongLink", "L", `${"a".repeat(120)}\0`),
+      member("short", "2", "", { link: "ignored" }),
+      END,
+    );
+    expect(listTarEntries(archive)).toEqual([
+      { name: "a".repeat(120), type: "symlink", linkTarget: "target" },
+    ]);
+  });
+
+  it("refuses a header whose checksum does not match — GNU tar would skip it and read its body as headers", () => {
+    const archive = concat(
+      header("srv/caelo/safe.txt", "0", { sizeField: 512, badChecksum: true }),
+      header("../../evil", "0"),
+      END,
+    );
+    expect(() => listTarEntries(archive)).toThrow(/checksum mismatch/);
+  });
+
+  it("refuses a directory or symlink with a body — bsdtar reads the next block as a header", () => {
+    for (const [name, type] of [
+      ["srv/caelo/link", "2"],
+      ["srv/caelo/dir/", "5"],
+    ] as const) {
+      const archive = concat(
+        header(name, type, { sizeField: 512, link: "a" }),
+        header("../../evil", "0"),
+        END,
+      );
+      expect(() => listTarEntries(archive)).toThrow(/with a body/);
+    }
+  });
+
+  it("walks a member's body by its pax size, so a member hidden behind the header size is seen", () => {
+    // tar -x reads `safe.txt` as empty (pax size=0) and then extracts the
+    // `../../evil` header that the ustar size field claims is file data.
+    const archive = concat(
+      member("PaxHeader", "x", paxLine("size=0")),
+      header("safe.txt", "0", { sizeField: 512 }),
+      member("../../evil", "0"),
+      END,
+    );
+    expect(listTarEntries(archive).map((e) => e.name)).toEqual(["safe.txt", "../../evil"]);
+  });
+
+  it("rejects GNU sparse pax records and an unreadable pax size", () => {
+    const sparse = member("PaxHeader", "x", paxLine("GNU.sparse.name=../../evil"));
+    expect(() => listTarEntries(concat(sparse, member("safe.txt", "0")))).toThrow(/GNU sparse/);
+    const badSize = member("PaxHeader", "x", paxLine("size=-1"));
+    expect(() => listTarEntries(concat(badSize, member("safe.txt", "0")))).toThrow(
+      /unreadable pax size/,
+    );
   });
 });
 
-describe("escapesRoot", () => {
-  it("flags absolute and parent-relative member names", () => {
+const END = new Uint8Array(1024);
+
+/**
+ * One ustar header block with a valid checksum (unless `badChecksum`).
+ * `sizeField` is what the header claims, independent of any body after it.
+ */
+function header(
+  name: string,
+  typeflag: string,
+  opts: { sizeField?: number; link?: string; badChecksum?: boolean } = {},
+): Uint8Array {
+  const enc = new TextEncoder();
+  const h = new Uint8Array(512);
+  h.set(enc.encode(name), 0);
+  h.set(enc.encode(`${(opts.sizeField ?? 0).toString(8).padStart(11, "0")}\0`), 124);
+  h[156] = typeflag.charCodeAt(0);
+  if (opts.link) h.set(enc.encode(opts.link), 157);
+  h.set(enc.encode("ustar\0"), 257);
+  h.fill(0x20, 148, 156);
+  const sum = h.reduce((n, b) => n + b, 0) + (opts.badChecksum ? 1 : 0);
+  h.set(enc.encode(`${sum.toString(8).padStart(6, "0")}\0 `), 148);
+  return h;
+}
+
+/** A header plus its padded body. */
+function member(name: string, typeflag: string, bodyText = "", opts: { link?: string } = {}) {
+  const body = new TextEncoder().encode(bodyText);
+  const out = new Uint8Array(512 + Math.ceil(body.length / 512) * 512);
+  out.set(header(name, typeflag, { sizeField: body.length, link: opts.link }), 0);
+  out.set(body, 512);
+  return out;
+}
+
+/** One pax record; its leading length counts its own digits. */
+function paxLine(kv: string): string {
+  const base = ` ${kv}\n`;
+  const len = String(base.length + 2).length + base.length;
+  return `${len}${base}`;
+}
+
+function concat(...parts: Uint8Array[]): Uint8Array {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let at = 0;
+  for (const p of parts) {
+    out.set(p, at);
+    at += p.length;
+  }
+  return out;
+}
+
+describe("escapesRoot & normalizeMemberName", () => {
+  it("flags absolute, parent-relative, and dot-segment member names", () => {
     expect(escapesRoot("/etc/passwd")).toBe(true);
     expect(escapesRoot("srv/caelo/../../app")).toBe(true);
+    expect(escapesRoot(".//../etc/passwd")).toBe(true);
+    expect(escapesRoot("a/./b")).toBe(true);
     expect(escapesRoot("./srv/caelo/a..b")).toBe(false);
+    expect(normalizeMemberName(".//srv//caelo/")).toBe("srv/caelo");
   });
 });

package/src/tar-entries.ts

@@ -7,12 +7,34 @@
  * otherwise land outside the target directory).
  *
  * Parses ustar headers plus the two extensions GNU tar and bsdtar emit for
- * long names: GNU `L`/`K` records and pax `x`/`g` records (`path=`,
- * `linkpath=`). Anything it cannot read is an error, never a skipped member.
+ * long names: GNU `L`/`K` records and pax `x` records (`path=`, `linkpath=`,
+ * `size=`). Anything it cannot read is an error, never a skipped member.
+ *
+ * The parser must walk the archive exactly as `tar -x` will: a pax `size=`
+ * overrides the header's size field for the next member, so ignoring it
+ * would let an archive hide a member from this check inside what the parser
+ * takes for a body. Records that rename a member in ways it does not model
+ * (pax global `g` headers, GNU sparse `GNU.sparse.*` keys) are refused.
+ *
+ * Wherever GNU tar and bsdtar read the same bytes differently, the archive is
+ * refused rather than read one way: no Caelo backup is ever written like that,
+ * and whichever reading this module picked, the other tar would extract
+ * something it never checked.
+ * - A header whose checksum does not match: GNU tar skips it and reads the
+ *   next block as a header, so a member hidden in the "body" gets extracted.
+ * - A directory or symlink with a non-zero size: bsdtar reads no body for
+ *   them, so the block after the header is the next member's header.
+ * - Two name records for one member (two pax `x` headers, two `L`/`K`, or
+ *   `L`/`K` next to `x`): GNU tar keeps only the last `x` header, bsdtar
+ *   flags the second as malformed and drops it, and the two tars disagree
+ *   on whether a GNU long name or a pax path wins.
  */
 
 const BLOCK = 512;
 
+/** The extension headers one member may carry: one pax record, or a GNU long name and/or long link. */
+const SINGLE_NAMING = new Set(["x", "L", "K", "LK", "KL"]);
+
 export type TarEntryType = "file" | "directory" | "symlink" | "other";
 
 export interface TarEntry {
@@ -30,15 +52,34 @@ export function listTarEntries(tar: Uint8Array): TarEntry[] {
   let longLink: string | null = null;
   let paxPath: string | null = null;
   let paxLink: string | null = null;
+  let paxSize: number | null = null;
+  // The extension headers already seen for the member being read.
+  let extensions = "";
   while (offset + BLOCK <= tar.length) {
     const header = tar.subarray(offset, offset + BLOCK);
     if (header.every((b) => b === 0)) break; // end-of-archive marker
-    const size = octal(header.subarray(124, 136));
+    verifyChecksum(header);
     const typeflag = String.fromCharCode(header[156] ?? 0);
+    // A pax `size=` describes the member that follows the pax header, never
+    // another extension header (GNU tar applies it the same way).
+    const isExtension =
+      typeflag === "x" || typeflag === "g" || typeflag === "L" || typeflag === "K";
+    const size = !isExtension && paxSize !== null ? paxSize : octal(header.subarray(124, 136));
     const body = tar.subarray(offset + BLOCK, offset + BLOCK + size);
     if (body.length < size) throw new Error("truncated tar archive");
     offset += BLOCK + Math.ceil(size / BLOCK) * BLOCK;
 
+    if (typeflag === "g") {
+      throw new Error("tar archive contains unsupported pax global extended header");
+    }
+    if (isExtension) {
+      extensions += typeflag;
+      if (!SINGLE_NAMING.has(extensions)) {
+        throw new Error(
+          `tar archive names one member through several extension headers (${extensions}) — tar implementations disagree on which one wins`,
+        );
+      }
+    }
     if (typeflag === "L") {
       longName = cString(body);
       continue;
@@ -47,11 +88,18 @@ export function listTarEntries(tar: Uint8Array): TarEntry[] {
       longLink = cString(body);
       continue;
     }
-    if (typeflag === "x" || typeflag === "g") {
+    if (typeflag === "x") {
       const pax = paxRecords(body);
-      if (typeflag === "x") {
-        paxPath = pax.path ?? null;
-        paxLink = pax.linkpath ?? null;
+      if (Object.keys(pax).some((key) => key.startsWith("GNU.sparse."))) {
+        throw new Error("tar archive contains an unsupported GNU sparse member");
+      }
+      paxPath = pax.path ?? null;
+      paxLink = pax.linkpath ?? null;
+      if (pax.size !== undefined) {
+        if (!/^[0-9]+$/.test(pax.size)) {
+          throw new Error(`unreadable pax size ${JSON.stringify(pax.size)}`);
+        }
+        paxSize = Number.parseInt(pax.size, 10);
       }
       continue;
     }
@@ -60,6 +108,8 @@ export function listTarEntries(tar: Uint8Array): TarEntry[] {
     const name = paxPath ?? longName ?? (prefix ? `${prefix}/${shortName}` : shortName);
     const link = paxLink ?? longLink ?? cString(header.subarray(157, 257));
     longName = longLink = paxPath = paxLink = null;
+    paxSize = null;
+    extensions = "";
     const type: TarEntryType =
       typeflag === "0" || typeflag === "\0" || typeflag === "7"
         ? "file"
@@ -68,6 +118,9 @@ export function listTarEntries(tar: Uint8Array): TarEntry[] {
           : typeflag === "2"
             ? "symlink"
             : "other";
+    if (type !== "file" && size !== 0) {
+      throw new Error(`tar member ${JSON.stringify(name)} is a ${type} with a body`);
+    }
     entries.push(type === "symlink" ? { name, type, linkTarget: link } : { name, type });
   }
   return entries;
@@ -75,12 +128,40 @@ export function listTarEntries(tar: Uint8Array): TarEntry[] {
 
 /** `./a/b/` → `a/b`; the archive root (`./`) → "". */
 export function normalizeMemberName(name: string): string {
-  return name.replace(/^(\.\/)+/, "").replace(/\/+$/, "");
+  return name
+    .replace(/\/+/g, "/")
+    .replace(/^(\.\/)+/, "")
+    .replace(/\/+$/, "");
 }
 
 /** Whether a member name could write outside the extraction directory. */
 export function escapesRoot(name: string): boolean {
-  return name.startsWith("/") || name.split("/").some((part) => part === "..");
+  const normalized = name.replace(/\/+/g, "/").replace(/^(\.\/)+/, "");
+  return (
+    name.startsWith("/") || normalized.split("/").some((part) => part === ".." || part === ".")
+  );
+}
+
+/**
+ * Refuse a header whose checksum does not match, as `tar -x` would — except
+ * GNU tar then goes on reading at the next block, which this check must not.
+ * The sum counts the checksum field as spaces; old tars summed signed bytes,
+ * which GNU tar and bsdtar both still accept.
+ */
+function verifyChecksum(header: Uint8Array): void {
+  const recorded = cString(header.subarray(148, 156)).trim();
+  if (!/^[0-7]+$/.test(recorded)) throw new Error("unreadable tar header checksum");
+  let unsigned = 0;
+  let signed = 0;
+  for (let i = 0; i < BLOCK; i++) {
+    const b = i >= 148 && i < 156 ? 0x20 : (header[i] ?? 0);
+    unsigned += b;
+    signed += b > 127 ? b - 256 : b;
+  }
+  const expected = Number.parseInt(recorded, 8);
+  if (expected !== unsigned && expected !== signed) {
+    throw new Error("tar header checksum mismatch — the archive is damaged or was altered");
+  }
 }
 
 function octal(field: Uint8Array): number {