@le-space/rootfs 0.6.0 → 0.6.2

package/README.md

@@ -9,6 +9,8 @@ Shared rootfs contract parsing, reference profile assets, and build helpers.
 - copied `uc-go-peer` reference contract and guest asset set
 - copied `orbitdb-relay` reference contract and guest asset set,
   including the delayed first-start, setup endpoint, Caddy, and AutoTLS flow
+- added a `ucan-store` reference contract scaffold with documented service
+  ports and consumer env expectations
 
 ## Reference assets
 
@@ -18,3 +20,5 @@ Current shared reference profiles live under:
 - `reference/uc-go-peer/rootfs/*`
 - `reference/orbitdb-relay/contract.json`
 - `reference/orbitdb-relay/rootfs/*`
+- `reference/ucan-store/contract.json`
+- `reference/ucan-store/rootfs/*`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@le-space/rootfs",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Shared rootfs contract parsing, reference profile assets, and build helpers.",
   "license": "MIT",
   "type": "module",

package/reference/ucan-store/README.md

@@ -0,0 +1,89 @@
+# ucan-store Rootfs Profile
+
+This profile is the shared `relay-button` scaffold for deploying the
+`ucan-store` upload service VM that backs the rebranded upload wall.
+
+Current scope:
+
+- shared rootfs contract for the `ucan-store` profile
+- required public VM ports for Aleph guest setup plus the proxied upload API
+- documented browser/runtime configuration inputs used by the existing PWA
+- a prebaked qcow2 scaffold for the current local upload service runtime
+- guest-side setup/configure scripts that publish the service URLs and DID back to deployment tooling
+- stable guest-side service signer persistence with an Ed25519 default and hostname-aware DID selection
+- a guest-side request guard that narrows public UCAN invocations to the configured bootstrap envelope
+- a guest-side admin delegation issuance API that can mint importable child delegations from the service DID
+- a public service manifest endpoint for domain-first runtime discovery by a generic PWA
+
+Known inputs from the current `ucan-upload-wall` sources:
+
+- Internal upload API process port: `STORACHA_LOCAL_PORT` with default `8787`
+- Internal bootstrap-policy request guard port: `UCAN_STORE_PROXY_PORT` with default `8788`
+- Local WebAuthn origin inputs: `WEBAUTHN_ORIGIN`, `WEBAUTHN_ORIGIN_FALLBACKS`
+- Browser upload-service wiring:
+  - `VITE_UPLOAD_SERVICE_URL`
+  - `VITE_UPLOAD_SERVICE_DID`
+  - `VITE_REVOCATION_URL`
+  - `VITE_REVOCATION_DID`
+  - `VITE_RECEIPTS_URL`
+- Optional direct Helia test wiring:
+  - `VITE_HELIA_PEER_ID`
+  - `VITE_HELIA_ADDRS`
+
+What is not implemented yet in this shared profile:
+
+- a fixed public Helia/libp2p listener contract for direct IPFS fetches
+- service-specific Aleph VM workflow glue for full bootstrap-package collection in `relay-button`
+
+Current bootstrap-package support in this shared profile:
+
+- canonical JSON bootstrap package shape accepted by the shared node deploy runner
+- guest-side storage of the bootstrap package on the VM
+- guest-side structural validation for:
+  - `operatorAddress`
+  - `adminDid`
+  - optional `serviceDid`
+  - `spaceDid`
+  - `rootDelegationProof`
+  - `allowedCapabilities`
+  - delegation expiration policy
+  - `pwaOrigin`
+  - `serviceOrigin`
+- runtime consistency checks that compare:
+  - bootstrap `serviceDid` against the running service DID when provided
+  - bootstrap `serviceOrigin` against the configured public upload-service origin
+- `ucan-store.service` startup gating that:
+  - requires a bootstrap package by default
+  - re-validates the package before the service stays up
+  - probes the live `did:web` document and rejects startup on DID/origin mismatches
+- stable service identity handling that:
+  - persists one Ed25519 signer on the VM under `/var/lib/ucan-store`
+  - reuses that signer across restarts instead of generating a fresh test key
+  - prefers an explicit `UCAN_STORE_SERVICE_DID` override when configured
+  - otherwise derives `did:web:<proxy-hostname>` once a public hostname is assigned
+  - otherwise falls back to the persisted signer `did:key`
+- cryptographic bootstrap proof verification that checks:
+  - root delegation signature
+  - root delegation issuer against `adminDid`
+  - root delegation audience against the configured service DID
+  - delegation lifetime (`nbf` / `exp`)
+  - coverage of the configured `allowedCapabilities` for the configured `spaceDid`
+- request-time public invocation narrowing that rejects:
+  - capabilities outside the configured `allowedCapabilities`
+  - requests for a different `spaceDid`
+  - invocation proof trees that do not include the configured bootstrap root delegation
+- service-side user delegation issuance that:
+  - uses the persisted service signer as issuer
+  - chains back to the stored root bootstrap delegation
+  - exports a CAR-backed `m...` proof string the current UI can import directly
+  - enforces configured capability and expiration policy
+  - can be protected with `UCAN_STORE_ADMIN_API_TOKEN`
+- public service discovery metadata that:
+  - is exposed at `/.well-known/ucan-store.json`
+  - has a `/service-manifest.json` alias
+  - surfaces service DID/origin, PWA origin, allowed capabilities, and
+    delegation issuance metadata for runtime binding
+
+This still does not emit protocol-native UCAN error receipts from the guard
+layer yet; rejected requests currently fail at HTTP level before they reach the
+underlying upload API.

package/reference/ucan-store/contract.json

@@ -0,0 +1,46 @@
+{
+  "schemaVersion": 1,
+  "id": "ucan-store",
+  "displayName": "UCAN Store Upload Service",
+  "source": {
+    "repository": "external",
+    "subdirectory": "."
+  },
+  "rootfs": {
+    "profile": "ucan-store",
+    "installMode": "prebaked",
+    "installDir": "/opt/ucan-store",
+    "binaryPath": "/usr/local/bin/ucan-store",
+    "dataDir": "/var/lib/ucan-store",
+    "envFile": "/etc/default/ucan-store"
+  },
+  "services": {
+    "bootstrap": "ucan-store-bootstrap.service",
+    "main": "ucan-store.service",
+    "autotlsRefresh": "ucan-store-autotls-refresh.service"
+  },
+  "ports": [
+    {
+      "port": 22,
+      "tcp": true,
+      "udp": false,
+      "purpose": "SSH"
+    },
+    {
+      "port": 80,
+      "tcp": true,
+      "udp": false,
+      "purpose": "Temporary setup endpoint"
+    },
+    {
+      "port": 443,
+      "tcp": true,
+      "udp": false,
+      "purpose": "HTTPS upload API, did:web discovery, revocation, and receipt proxy"
+    }
+  ],
+  "manifest": {
+    "copyTarget": "web/public/rootfs/ucan-store/latest.json",
+    "notes": "The ucan-store image prebakes the current upload-wall local upload service into the Aleph guest, keeps the upstream HTTP worker on internal port 8787, exposes a temporary guest setup endpoint on port 80, runs a bootstrap-policy request guard on internal port 8788, persists one Ed25519 service signer under /var/lib/ucan-store, and proxies the public upload API, did:web document, revocation, receipt, service manifest, and optional admin delegation issuance routes through Caddy on port 443 once a proxy hostname is assigned. The admin issuance API can export CAR-backed `m...` delegation proofs for manual UI import when UCAN_STORE_ADMIN_API_TOKEN is configured, and the public `/.well-known/ucan-store.json` manifest exposes runtime binding metadata for a generic PWA. The browser consumer currently wires the service with VITE_UPLOAD_SERVICE_URL, VITE_UPLOAD_SERVICE_DID, VITE_REVOCATION_URL, VITE_REVOCATION_DID, and VITE_RECEIPTS_URL. Helia/IPFS peer exposure remains a later milestone and is not part of this base contract."
+  }
+}

package/reference/ucan-store/rootfs/Dockerfile.rootfs

@@ -0,0 +1,24 @@
+FROM --platform=linux/amd64 debian:12
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV LIBGUESTFS_BACKEND=direct
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends \
+    ca-certificates \
+    curl \
+    libguestfs-tools \
+    linux-image-amd64 \
+    python3 \
+    qemu-system-x86 \
+    qemu-utils \
+    tar \
+  && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /workspace/shared-rootfs
+
+COPY . .
+
+RUN chmod 0755 ./build-rootfs.sh ./build-rootfs-image.sh ./read-rootfs-contract.py \
+  ./ucan-store-bootstrap.sh ./ucan-store-configure.sh ./ucan-store-bootstrap-verify.mjs ./ucan-store-request-guard.mjs ./ucan-store-describe.py ./ucan-store-service-start.sh ./ucan-store-setup-server.py \
+  ./ucan_store_bootstrap_validate.py ./ucan-store-upload-api-context.js ./ucan-store-upload-api-service-identity.js

package/reference/ucan-store/rootfs/README.md

@@ -0,0 +1,84 @@
+# ucan-store Rootfs Runtime
+
+This shared rootfs profile packages the current `ucan-upload-wall` local upload
+service into an Aleph guest image.
+
+Runtime shape:
+
+- `80/tcp`: temporary setup endpoint used by deployment tooling before first start
+- `443/tcp`: public HTTPS proxy for upload API, `did:web`, revocations, and receipts
+- internal `127.0.0.1:8787`: upstream upload API worker from `local-storacha-api`
+- internal `127.0.0.1:8788`: bootstrap-policy request guard in front of the upload API
+
+Service identity shape:
+
+- default signer algorithm: `Ed25519`
+- signer persistence: `/var/lib/ucan-store/service-ed25519.key`
+- explicit DID override: `UCAN_STORE_SERVICE_DID`
+- hostname-derived DID fallback: `did:web:<proxy-hostname>`
+- no-host fallback: persisted `did:key`
+
+Delegation issuance shape:
+
+- admin endpoint: `POST /admin/delegations`
+- policy endpoint: `GET /admin/delegations/policy`
+- auth: `Authorization: Bearer $UCAN_STORE_ADMIN_API_TOKEN`
+- export format: `m...` multibase base64 UCAN CAR proof string
+- chaining: child delegations include the persisted bootstrap root delegation as proof
+
+Service discovery shape:
+
+- public manifest: `GET /.well-known/ucan-store.json`
+- alias: `GET /service-manifest.json`
+- purpose: expose service DID/origin, PWA origin, allowed capabilities, and
+  delegation issuance metadata for a generic domain-bound PWA
+
+The guest publishes metadata for the browser PWA after configuration, including:
+
+- `VITE_UPLOAD_SERVICE_URL`
+- `VITE_UPLOAD_SERVICE_DID`
+- `VITE_REVOCATION_URL`
+- `VITE_REVOCATION_DID`
+- `VITE_RECEIPTS_URL`
+
+Not included in this base milestone:
+
+- public Helia/libp2p exposure
+- Filecoin/archive publishing glue
+
+Bootstrap package handling in the current guest scaffold:
+
+- the setup endpoint now accepts a canonical `bootstrap_package` JSON object
+- the package is persisted on the VM for the running upload service
+- guest metadata includes a `bootstrap_validation` summary
+- guest metadata now also includes `bootstrap_proof_validation`
+- guest metadata now also includes `service_identity`
+- guest metadata now also includes `delegation_issuance`
+- guest metadata now also includes `service_manifest`
+- invalid package shape or runtime mismatches fail metadata publication
+- `ucan-store.service` now verifies the persisted package again at startup and
+  refuses to keep the upload service running when the package is missing
+  (by default), malformed, or inconsistent with the runtime DID/origin
+- the upload service now reuses one persisted Ed25519 signer on the VM instead
+  of generating a fresh test identity on every boot
+- the request guard can now mint long-lived service-to-user delegations when an
+  admin bearer token is configured, enforcing:
+  - `allowedCapabilities`
+  - `spaceDid`
+  - `defaultUserDelegationExpiration`
+  - `maxUserDelegationExpiration`
+- the request guard now also publishes a public runtime manifest that a generic
+  PWA can fetch via the service domain without relying on build-time-only
+  `VITE_UPLOAD_SERVICE_*` values
+- the guest now performs cryptographic verification of the bootstrap root
+  delegation with the installed `ucanto` / Storacha packages before the
+  service is allowed to stay up
+- public requests now pass through a local request guard that only forwards
+  UCAN invocations when:
+  - the invocation capability `with` matches the configured `spaceDid`
+  - the invocation `can` stays inside the configured `allowedCapabilities`
+  - the invocation proof tree includes the configured bootstrap root delegation
+
+The current guest still does not expose this issuance flow through
+`relay-button` yet, and it still does not provide signed multi-tenant manifest
+publication; those remain follow-up steps.

package/reference/ucan-store/rootfs/build-rootfs-image.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="${PROJECT_DIR:-$(cd "${SCRIPT_DIR}/../../../../.." && pwd)}"
+ROOTFS_CONTRACT_FILE="${ROOTFS_CONTRACT_FILE:-${PROJECT_DIR}/root-profiles/ucan-store.json}"
+OUT_DIR="${OUT_DIR:-${PROJECT_DIR}/dist-rootfs}"
+BASE_URL="${BASE_URL:-https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2}"
+BASE_IMAGE="${OUT_DIR}/debian-12-genericcloud-amd64.qcow2"
+IMAGE="${OUT_DIR}/aleph-ucan-store.qcow2"
+APP_TAR="${OUT_DIR}/ucan-store-runtime.tar"
+ROOTFS_IMAGE_SIZE="${ROOTFS_IMAGE_SIZE:-20G}"
+ROOTFS_SPARSIFY="${ROOTFS_SPARSIFY:-1}"
+HOST_UID="${HOST_UID:-}"
+HOST_GID="${HOST_GID:-}"
+
+require() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "Missing required command: $1" >&2
+    exit 1
+  }
+}
+
+require curl
+require qemu-img
+require virt-customize
+require python3
+require tar
+
+eval "$(python3 "${SCRIPT_DIR}/read-rootfs-contract.py" "${ROOTFS_CONTRACT_FILE}")"
+
+if [ "${ROOTFS_CONTRACT_PROFILE}" != "ucan-store" ]; then
+  echo "Only the ucan-store rootfs profile is supported, got: ${ROOTFS_CONTRACT_PROFILE}" >&2
+  exit 1
+fi
+if [ "${ROOTFS_CONTRACT_INSTALL_MODE}" != "prebaked" ]; then
+  echo "Only prebaked install mode is supported, got: ${ROOTFS_CONTRACT_INSTALL_MODE}" >&2
+  exit 1
+fi
+if [ ! -d "${PROJECT_DIR}/local-storacha-api" ]; then
+  echo "Missing local-storacha-api directory: ${PROJECT_DIR}/local-storacha-api" >&2
+  exit 1
+fi
+if [ ! -f "${PROJECT_DIR}/web/package.json" ]; then
+  echo "Missing web/package.json: ${PROJECT_DIR}/web/package.json" >&2
+  exit 1
+fi
+if [ ! -f "${PROJECT_DIR}/web/package-lock.json" ]; then
+  echo "Missing web/package-lock.json: ${PROJECT_DIR}/web/package-lock.json" >&2
+  echo "The current ucan-store rootfs scaffold expects the upload wall web app to use npm lockfiles." >&2
+  exit 1
+fi
+
+mkdir -p "${OUT_DIR}"
+
+echo "Building ucan-store image in prebaked mode"
+
+if [ ! -f "${BASE_IMAGE}" ]; then
+  echo "Downloading base image from ${BASE_URL}"
+  curl --fail --show-error --location \
+    --retry 5 \
+    --retry-all-errors \
+    --retry-delay 5 \
+    --connect-timeout 20 \
+    --max-time 300 \
+    "${BASE_URL}" -o "${BASE_IMAGE}"
+fi
+
+cp "${BASE_IMAGE}" "${IMAGE}"
+qemu-img resize "${IMAGE}" "${ROOTFS_IMAGE_SIZE}"
+
+tar \
+  --exclude ".git" \
+  -C "${PROJECT_DIR}" \
+  -cf "${APP_TAR}" \
+  local-storacha-api \
+  web/package.json \
+  web/package-lock.json \
+  README.md
+
+virt-customize \
+  -a "${IMAGE}" \
+  --mkdir "${ROOTFS_CONTRACT_INSTALL_DIR}" \
+  --mkdir "${ROOTFS_CONTRACT_DATA_DIR}" \
+  --mkdir /usr/local/share/ucan-store \
+  --copy-in "${APP_TAR}:/opt" \
+  --copy-in "${SCRIPT_DIR}/ucan-store-bootstrap.sh:/usr/local/sbin" \
+  --copy-in "${SCRIPT_DIR}/ucan-store-configure.sh:/usr/local/sbin" \
+  --copy-in "${SCRIPT_DIR}/ucan-store-bootstrap-verify.mjs:/usr/local/sbin" \
+  --copy-in "${SCRIPT_DIR}/ucan-store-request-guard.mjs:/usr/local/sbin" \
+  --copy-in "${SCRIPT_DIR}/ucan-store-upload-api-context.js:/usr/local/share/ucan-store" \
+  --copy-in "${SCRIPT_DIR}/ucan-store-upload-api-service-identity.js:/usr/local/share/ucan-store" \
+  --copy-in "${SCRIPT_DIR}/ucan-store-describe.py:/usr/local/sbin" \
+  --copy-in "${SCRIPT_DIR}/ucan-store-setup-server.py:/usr/local/sbin" \
+  --copy-in "${SCRIPT_DIR}/ucan-store-service-start.sh:/usr/local/sbin" \
+  --copy-in "${SCRIPT_DIR}/ucan_store_bootstrap_validate.py:/usr/local/sbin" \
+  --copy-in "${SCRIPT_DIR}/ucan-store-bootstrap.service:/etc/systemd/system" \
+  --copy-in "${SCRIPT_DIR}/ucan-store-autotls-refresh.service:/etc/systemd/system" \
+  --copy-in "${SCRIPT_DIR}/ucan-store.service:/etc/systemd/system" \
+  --run-command "tar -xf /opt/$(basename "${APP_TAR}") -C ${ROOTFS_CONTRACT_INSTALL_DIR}" \
+  --run-command "chmod 0755 /usr/local/sbin/ucan-store-bootstrap.sh" \
+  --run-command "chmod 0755 /usr/local/sbin/ucan-store-configure.sh" \
+  --run-command "chmod 0755 /usr/local/sbin/ucan-store-bootstrap-verify.mjs" \
+  --run-command "chmod 0755 /usr/local/sbin/ucan-store-request-guard.mjs" \
+  --run-command "chmod 0755 /usr/local/sbin/ucan-store-describe.py" \
+  --run-command "chmod 0755 /usr/local/sbin/ucan-store-setup-server.py" \
+  --run-command "chmod 0755 /usr/local/sbin/ucan-store-service-start.sh" \
+  --run-command "chmod 0755 /usr/local/sbin/ucan_store_bootstrap_validate.py" \
+  --run-command "INSTALL_DIR=${ROOTFS_CONTRACT_INSTALL_DIR} DATA_DIR=${ROOTFS_CONTRACT_DATA_DIR} ENV_FILE=${ROOTFS_CONTRACT_ENV_FILE} SERVICE_USER=ucan-store APP_BINARY=${ROOTFS_CONTRACT_BINARY_PATH} /usr/local/sbin/ucan-store-bootstrap.sh all" \
+  --run-command "systemctl enable ${ROOTFS_CONTRACT_BOOTSTRAP_SERVICE}" \
+  --run-command "systemctl enable ${ROOTFS_CONTRACT_AUTOTLS_SERVICE}" \
+  --run-command "systemctl enable ${ROOTFS_CONTRACT_MAIN_SERVICE}" \
+  --run-command "rm -f /opt/$(basename "${APP_TAR}")"
+
+if [ "${ROOTFS_SPARSIFY}" = "1" ] && command -v virt-sparsify >/dev/null 2>&1; then
+  SPARSE_IMAGE="${IMAGE%.qcow2}.sparse.qcow2"
+  rm -f "${SPARSE_IMAGE}"
+  echo "Sparsifying and compressing ${IMAGE}..."
+  virt-sparsify --compress "${IMAGE}" "${SPARSE_IMAGE}"
+  mv "${SPARSE_IMAGE}" "${IMAGE}"
+fi
+
+echo "Rootfs image ready at ${IMAGE}"
+
+if [ -n "${HOST_UID}" ] && [ -n "${HOST_GID}" ]; then
+  chown -R "${HOST_UID}:${HOST_GID}" "${OUT_DIR}"
+fi

package/reference/ucan-store/rootfs/build-rootfs.sh

@@ -0,0 +1,242 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+APP_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+PROJECT_DIR="${PROJECT_DIR:-$(cd "${SCRIPT_DIR}/../../../../.." && pwd)}"
+OUT_DIR="${OUT_DIR:-${APP_DIR}/dist-rootfs}"
+ROOTFS_CONTRACT_FILE="${ROOTFS_CONTRACT_FILE:-${PROJECT_DIR}/root-profiles/ucan-store.json}"
+ROOTFS_BUILD_DRIVER="${ROOTFS_BUILD_DRIVER:-auto}"
+ROOTFS_SIZE_MIB="${ROOTFS_SIZE_MIB:-20480}"
+ROOTFS_IMAGE_SIZE="${ROOTFS_IMAGE_SIZE:-20G}"
+ROOTFS_VERSION="${ROOTFS_VERSION:-}"
+CHANNEL="${CHANNEL:-ALEPH-CLOUDSOLUTIONS}"
+SKIP_UPLOAD="${SKIP_UPLOAD:-0}"
+SKIP_BUILD="${SKIP_BUILD:-0}"
+IPFS_ADD_URL="${IPFS_ADD_URL:-https://ipfs.aleph.cloud/api/v0/add}"
+ROOTFS_CID=""
+ROOTFS_ITEM_HASH=""
+
+require() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "Missing required command: $1" >&2
+    exit 1
+  }
+}
+
+die() {
+  echo "$*" >&2
+  exit 1
+}
+
+load_rootfs_contract() {
+  require python3
+  [ -f "${ROOTFS_CONTRACT_FILE}" ] || die "Rootfs contract does not exist: ${ROOTFS_CONTRACT_FILE}"
+  eval "$(python3 "${SCRIPT_DIR}/read-rootfs-contract.py" "${ROOTFS_CONTRACT_FILE}")"
+
+  if [ "${ROOTFS_CONTRACT_PROFILE}" != "ucan-store" ]; then
+    die "Only the ucan-store rootfs profile is supported, got: ${ROOTFS_CONTRACT_PROFILE}"
+  fi
+  if [ "${ROOTFS_CONTRACT_INSTALL_MODE}" != "prebaked" ]; then
+    die "Only prebaked install mode is supported, got: ${ROOTFS_CONTRACT_INSTALL_MODE}"
+  fi
+}
+
+resolve_rootfs_version() {
+  if [ -n "${ROOTFS_VERSION}" ]; then
+    printf '%s\n' "${ROOTFS_VERSION}"
+    return
+  fi
+
+  if [ -d "${PROJECT_DIR}/.git" ]; then
+    local short_sha
+    short_sha="$(git -C "${PROJECT_DIR}" rev-parse --short HEAD)"
+    local build_date
+    build_date="$(date -u +%Y%m%d)"
+    printf 'ucan-store-git-%s-%s\n' "${build_date}" "${short_sha}"
+    return
+  fi
+
+  printf 'ucan-store-v0.1.0\n'
+}
+
+build_with_host_tools() {
+  echo "Using host virt-customize/qemu-img toolchain."
+  ROOTFS_CONTRACT_FILE="${ROOTFS_CONTRACT_FILE}" \
+  OUT_DIR="${OUT_DIR}" \
+  ROOTFS_IMAGE_SIZE="${ROOTFS_IMAGE_SIZE}" \
+  PROJECT_DIR="${PROJECT_DIR}" \
+  bash "${SCRIPT_DIR}/build-rootfs-image.sh"
+}
+
+build_with_docker() {
+  require docker
+
+  if ! docker info >/dev/null 2>&1; then
+    die "Docker is installed, but the Docker daemon is not running."
+  fi
+
+  echo "Using Dockerized Debian/libguestfs builder."
+  docker build --platform linux/amd64 \
+    -t ucan-store-rootfs-builder:local \
+    -f "${SCRIPT_DIR}/Dockerfile.rootfs" \
+    "${SCRIPT_DIR}"
+
+  docker run --rm --privileged --platform linux/amd64 \
+    -e LIBGUESTFS_BACKEND=direct \
+    -e ROOTFS_CONTRACT_FILE=/workspace/shared-rootfs/input-rootfs-contract.json \
+    -e OUT_DIR=/workspace/ucan-store/dist-rootfs \
+    -e ROOTFS_IMAGE_SIZE="${ROOTFS_IMAGE_SIZE}" \
+    -e PROJECT_DIR=/workspace/ucan-store \
+    -v "${PROJECT_DIR}:/workspace/ucan-store" \
+    -v "${SCRIPT_DIR}:/workspace/shared-rootfs" \
+    -v "${ROOTFS_CONTRACT_FILE}:/workspace/shared-rootfs/input-rootfs-contract.json:ro" \
+    -w /workspace/shared-rootfs \
+    ucan-store-rootfs-builder:local \
+    /bin/bash /workspace/shared-rootfs/build-rootfs-image.sh
+}
+
+sync_manifest_copy_target() {
+  local manifest_path="${OUT_DIR}/rootfs-manifest.json"
+  local copy_target="${ROOTFS_CONTRACT_MANIFEST_COPY_TARGET:-}"
+  local resolved_target
+  local target_dir
+  local versioned_target
+
+  [ -n "${copy_target}" ] || return 0
+  [ -f "${manifest_path}" ] || die "Manifest does not exist: ${manifest_path}"
+
+  if [[ "${copy_target}" = /* ]]; then
+    resolved_target="${copy_target}"
+  else
+    resolved_target="${PROJECT_DIR}/${copy_target}"
+  fi
+
+  target_dir="$(dirname "${resolved_target}")"
+  mkdir -p "${target_dir}"
+  cp "${manifest_path}" "${resolved_target}"
+
+  versioned_target="${target_dir}/${ROOTFS_VERSION}.json"
+  cp "${manifest_path}" "${versioned_target}"
+
+  echo "Copied rootfs manifest to ${resolved_target}"
+  echo "Copied versioned rootfs manifest to ${versioned_target}"
+}
+
+write_manifest() {
+  local rootfs_cid="${1:-}"
+  local rootfs_item_hash="${2:-}"
+  local rootfs_source_size_bytes=""
+
+  if [ -f "${OUT_DIR}/ipfs-add-response.jsonl" ]; then
+    rootfs_source_size_bytes="$(python3 - "${OUT_DIR}/ipfs-add-response.jsonl" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+lines = [line for line in Path(sys.argv[1]).read_text().splitlines() if line.strip()]
+if not lines:
+    raise SystemExit(0)
+
+payload = json.loads(lines[-1])
+size = payload.get("Size")
+if isinstance(size, str) and size.isdigit():
+    print(size)
+elif isinstance(size, int) and size > 0:
+    print(size)
+PY
+)"
+  fi
+
+  {
+    echo '{'
+    echo '  "profile": "ucan-store",'
+    echo "  \"version\": \"${ROOTFS_VERSION}\","
+    echo '  "rootfsInstallStrategy": "prebaked",'
+    echo '  "requiresBootstrapNetwork": false,'
+    echo '  "bootstrapSummary": "Node.js, Caddy, and the current local upload service runtime are prebaked into the image.",'
+    if [[ "${rootfs_source_size_bytes}" =~ ^[0-9]+$ ]]; then
+      echo "  \"rootfsSourceSizeBytes\": ${rootfs_source_size_bytes},"
+    fi
+    printf '  "requiredPortForwards": %s,\n' "${ROOTFS_CONTRACT_PORT_FORWARDS_JSON}"
+    if [ -n "${rootfs_cid}" ]; then
+      echo "  \"rootfsCid\": \"${rootfs_cid}\","
+    fi
+    if [ -n "${rootfs_item_hash}" ]; then
+      echo "  \"rootfsItemHash\": \"${rootfs_item_hash}\","
+    fi
+    echo "  \"rootfsSizeMiB\": ${ROOTFS_SIZE_MIB},"
+    echo "  \"createdAt\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\","
+    printf '  "notes": "%s"\n' "${ROOTFS_CONTRACT_MANIFEST_NOTES}"
+    echo '}'
+  } > "${OUT_DIR}/rootfs-manifest.json"
+
+  echo "Rootfs manifest written to ${OUT_DIR}/rootfs-manifest.json"
+  sync_manifest_copy_target
+}
+
+upload_rootfs_to_ipfs() {
+  require curl
+  [ -f "${OUT_DIR}/aleph-ucan-store.qcow2" ] || die "Missing rootfs image: ${OUT_DIR}/aleph-ucan-store.qcow2"
+
+  curl --fail --show-error --silent \
+    -X POST \
+    -F "file=@${OUT_DIR}/aleph-ucan-store.qcow2" \
+    "${IPFS_ADD_URL}" | tee "${OUT_DIR}/ipfs-add-response.jsonl" >/dev/null
+
+  ROOTFS_CID="$(python3 - "${OUT_DIR}/ipfs-add-response.jsonl" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+lines = [line for line in Path(sys.argv[1]).read_text().splitlines() if line.strip()]
+if not lines:
+    raise SystemExit("No IPFS add response lines found")
+payload = json.loads(lines[-1])
+cid = payload.get("Hash")
+if not isinstance(cid, str) or not cid.strip():
+    raise SystemExit("IPFS add response is missing Hash")
+print(cid.strip())
+PY
+)"
+
+  echo "Uploaded rootfs to IPFS with CID ${ROOTFS_CID}"
+}
+
+publish_store_message() {
+  [ -n "${ROOTFS_CID}" ] || die "Cannot publish rootfs STORE message without ROOTFS_CID"
+  die "Aleph STORE message publication is not wired for the shared ucan-store rootfs yet. Re-run with SKIP_UPLOAD=1 until the publication workflow is implemented."
+}
+
+load_rootfs_contract
+ROOTFS_VERSION="$(resolve_rootfs_version)"
+
+mkdir -p "${OUT_DIR}"
+
+if [ "${SKIP_BUILD}" != "1" ]; then
+  case "${ROOTFS_BUILD_DRIVER}" in
+    host)
+      build_with_host_tools
+      ;;
+    docker)
+      build_with_docker
+      ;;
+    auto)
+      if command -v virt-customize >/dev/null 2>&1 && command -v qemu-img >/dev/null 2>&1; then
+        build_with_host_tools
+      else
+        build_with_docker
+      fi
+      ;;
+    *)
+      die "Unsupported ROOTFS_BUILD_DRIVER=${ROOTFS_BUILD_DRIVER}"
+      ;;
+  esac
+fi
+
+if [ "${SKIP_UPLOAD}" != "1" ]; then
+  upload_rootfs_to_ipfs
+  publish_store_message
+fi
+
+write_manifest "${ROOTFS_CID}" "${ROOTFS_ITEM_HASH}"