feat(coupling): complete server-only protected materialization

.env.example

@@ -1,36 +1,24 @@
-COUPLING_SERVICE_SECRET=change-me
-COUPLING_SERVICE_HOST=0.0.0.0
-COUPLING_SERVICE_PORT=8788
-COUPLING_PUBLIC_BASE_URL=http://127.0.0.1:8788
-COUPLING_CONTROL_PLANE_BASE_URL=http://127.0.0.1:3210
-COUPLING_BROKER_SHARED_SECRET=change-me-too
-YUCP_ROOT_PUBLIC_KEY=
-# Optional Infisical-backed aliases:
-# - YUCP_COUPLING_SERVICE_SHARED_SECRET can supply the local service auth secret.
-# - YUCP_BROKER_SHARED_SECRET can supply the broker auth secret for Convex redeem/receipt.
-# - API_BASE_URL or SITE_URL can supply the control plane base URL when COUPLING_CONTROL_PLANE_BASE_URL is unset.
-# Prefer COUPLING_RUNTIME_LIBRARY_PATH and COUPLING_RUNTIME_LIBRARY_SHA256.
-# The older COUPLING_RUNTIME_DLL_* names are still accepted for compatibility.
-# Host-native defaults resolve to:
-# - Windows x64: .\yucp_coupling\out\win-x64\Release\yucp_coupling.dll
-# - Linux x64:   .\yucp_coupling\out\linux-x64\Release\yucp_coupling.so
-# - macOS arm64: .\yucp_coupling\out\darwin-arm64\Release\yucp_coupling.dylib
-COUPLING_RUNTIME_LIBRARY_PATH=
-COUPLING_RUNTIME_LIBRARY_SHA256=
-COUPLING_RUNTIME_ARTIFACT_PATH=.\yucp_coupling\out\win-x64\Release\runtime-helper\yucp_coupling.dll
-COUPLING_RUNTIME_ARTIFACT_VERSION=
-COUPLING_RUNTIME_ARTIFACT_CHANNEL=stable
-COUPLING_RUNTIME_ARTIFACT_PLATFORM=win-x64
-COUPLING_RUNTIME_ARTIFACT_METADATA_VERSION=1
-COUPLING_RUNTIME_ARTIFACT_DELIVERY_NAME=yucp_coupling.dll
-COUPLING_RUNTIME_ARTIFACT_CODE_SIGNING_SUBJECT=
-COUPLING_RUNTIME_ARTIFACT_CODE_SIGNING_THUMBPRINT=
-COUPLING_RUNTIME_PACKAGE_ARTIFACT_PATH=
-COUPLING_RUNTIME_PACKAGE_ARTIFACT_VERSION=
-COUPLING_RUNTIME_PACKAGE_ARTIFACT_DELIVERY_NAME=yucp-coupling-runtime-package.zip
-COUPLING_RUNTIME_PACKAGE_ARTIFACT_CODE_SIGNING_SUBJECT=
-COUPLING_RUNTIME_PACKAGE_ARTIFACT_CODE_SIGNING_THUMBPRINT=
-COUPLING_WORK_ROOT=.\runtime-data
-COUPLING_MAX_ASSETS_PER_REQUEST=512
-COUPLING_MAX_FILE_BYTES=67108864
-# The service accepts either COUPLING_SERVICE_PORT or the generic PORT env.
+NODE_ENV=production
+MATERIALIZATION_CONTROL_PLANE_BASE_URL=https://api.example.com
+MATERIALIZATION_CHUNK_CACHE_MAX_BYTES=4294967296
+MATERIALIZATION_DPOP_PRIVATE_KEY_PKCS8=
+MATERIALIZATION_EMERGENCY_DISK_FLOOR_BYTES=13958643712
+MATERIALIZATION_HEALTH_HOST=127.0.0.1
+MATERIALIZATION_HEALTH_PORT=8788
+MATERIALIZATION_KEY_BROKER_SHARED_SECRET=
+MATERIALIZATION_LANE=large
+MATERIALIZATION_LEASE_DURATION_MS=600000
+MATERIALIZATION_MATERIALIZER_SHARED_SECRET=
+MATERIALIZATION_MASTER_EPOCH_KEYS_FILE=
+MATERIALIZATION_POLL_INTERVAL_MS=1000
+MATERIALIZATION_RUNTIME_LIBRARY_PATH=
+MATERIALIZATION_SERVICE_ID=materializer-large-01
+MATERIALIZATION_WORK_ROOT=/var/lib/yucp-materializer
+YUCP_COUPLING_SERVICE_SHARED_SECRET=
+
+# Infisical can load the canonical variables above.
+INFISICAL_CLIENT_ID=
+INFISICAL_CLIENT_SECRET=
+INFISICAL_ENV=production
+INFISICAL_PROJECT_ID=
+INFISICAL_URL=https://app.infisical.com

deploy/initialize-local-master-credential.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+target="${HOME}/.config/yucp-materializer/materialization-master-epochs"
+epoch="${MATERIALIZATION_KEY_EPOCH:-1}"
+
+if [[ ! "${epoch}" =~ ^(0|[1-9][0-9]*)$ ]]; then
+  echo "The local materialization key epoch is invalid." >&2
+  exit 64
+fi
+if (( ${#epoch} > 16 )) ||
+  { (( ${#epoch} == 16 )) && [[ "${epoch}" > "9007199254740991" ]]; }; then
+  echo "The local materialization key epoch is invalid." >&2
+  exit 64
+fi
+
+install -d -m 700 "$(dirname "${target}")"
+umask 077
+exec 9>"${target}.lock"
+flock 9
+
+if [[ -e "${target}" ]]; then
+  if [[ -L "${target}" || ! -f "${target}" ]]; then
+    echo "The local materialization credential path is invalid." >&2
+    exit 78
+  fi
+  if [[ "$(stat -c '%u:%a' "${target}")" != "$(id -u):600" ]]; then
+    echo "The local materialization credential permissions are invalid." >&2
+    exit 78
+  fi
+fi
+
+temporary="$(mktemp "${target}.tmp.XXXXXX")"
+trap 'rm -f "${temporary}"' EXIT
+
+TARGET="${target}" EPOCH="${epoch}" bun --eval '
+  import { randomBytes } from "node:crypto";
+  import { readFileSync } from "node:fs";
+  const target = process.env.TARGET;
+  const epoch = process.env.EPOCH;
+  if (!target || !epoch) throw new Error("Credential target is incomplete");
+  let parsed = {};
+  try {
+    parsed = JSON.parse(readFileSync(target, "utf8"));
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Existing credential is invalid");
+  }
+  for (const [key, value] of Object.entries(parsed)) {
+    if (!/^(0|[1-9][0-9]*)$/.test(key) ||
+        !Number.isSafeInteger(Number(key)) || typeof value !== "string" ||
+        !/^[A-Za-z0-9_-]{43}$/.test(value)) {
+      throw new Error("Existing credential is invalid");
+    }
+  }
+  if (parsed[epoch] === undefined) {
+    parsed[epoch] = randomBytes(32).toString("base64url");
+  }
+  const ordered = Object.fromEntries(
+    Object.entries(parsed).sort(([left], [right]) => Number(left) - Number(right))
+  );
+  process.stdout.write(`${JSON.stringify(ordered)}\n`);
+' >"${temporary}"
+chmod 600 "${temporary}"
+mv -f "${temporary}" "${target}"
+trap - EXIT

deploy/initialize-local-master-credential.test.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+run_root="$(mktemp -d)"
+trap 'rm -rf -- "${run_root}"' EXIT
+export HOME="${run_root}"
+command -v bun >/dev/null
+
+MATERIALIZATION_KEY_EPOCH=9007199254740991 \
+  bash "${repo_root}/deploy/initialize-local-master-credential.sh"
+if MATERIALIZATION_KEY_EPOCH=9007199254740992 \
+  bash "${repo_root}/deploy/initialize-local-master-credential.sh"; then
+  echo "An unsafe materialization key epoch was accepted." >&2
+  exit 1
+fi
+
+MATERIALIZATION_KEY_EPOCH=1 \
+  bash "${repo_root}/deploy/initialize-local-master-credential.sh" &
+first_pid=$!
+MATERIALIZATION_KEY_EPOCH=2 \
+  bash "${repo_root}/deploy/initialize-local-master-credential.sh" &
+second_pid=$!
+first_status=0
+wait "${first_pid}" || first_status=$?
+second_status=0
+wait "${second_pid}" || second_status=$?
+test "${first_status}" -eq 0
+test "${second_status}" -eq 0
+
+target="${HOME}/.config/yucp-materializer/materialization-master-epochs"
+grep -q '"1":' "${target}"
+grep -q '"2":' "${target}"
+test "$(stat -c '%a' "${target}")" = "600"
+test -z "$(find "${HOME}" -name '*.tmp.*' -print -quit)"
+
+printf 'Concurrent credential initialization passed.\n'

deploy/prepare-local-wsl-materializer.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+source_root="${1:?The coupling source root is required.}"
+target="/home/yucp/ca-coupling"
+
+source_root="$(realpath -e -- "${source_root}")"
+case "${source_root}" in
+  /mnt/[A-Za-z]/*)
+    ;;
+  *)
+    echo "The coupling source root must use a mounted Windows drive." >&2
+    exit 64
+    ;;
+esac
+
+command -v rsync >/dev/null
+command -v socat >/dev/null
+command -v /home/yucp/.bun/bin/bun >/dev/null
+
+install -d -m 700 "${target}"
+rsync \
+  -a \
+  --chmod=Du=rwx,Dgo=,Fu=rw,Fgo= \
+  --delete \
+  --exclude=.env \
+  --exclude=.git \
+  --exclude=.idea \
+  --exclude=node_modules \
+  "${source_root}/" \
+  "${target}/"
+
+cd "${target}"
+chmod 700 deploy/*.sh
+/home/yucp/.bun/bin/bun install --frozen-lockfile
+
+test -f deploy/run-local-wsl-materializer.sh
+test -f deploy/initialize-local-master-credential.sh
+test -f yucp_coupling/out/linux-x64/Release/yucp_coupling.so
+test -f yucp_coupling/out/linux-x64/Release/yucp_coupling.sha256
+runtime_sha256="$(
+  cat yucp_coupling/out/linux-x64/Release/yucp_coupling.sha256
+)"
+if [[ ! "${runtime_sha256}" =~ ^[0-9a-f]{64}$ ]]; then
+  echo "The coupling runtime digest is invalid." >&2
+  exit 78
+fi
+printf '%s  %s\n' \
+  "${runtime_sha256}" \
+  "yucp_coupling/out/linux-x64/Release/yucp_coupling.so" |
+  sha256sum --check --status -