diff --git a/.dockerignore b/.dockerignore index 5b1530c..0b2564a 100644 --- a/.dockerignore +++ b/.dockerignore @@ -8,5 +8,6 @@ deploy/ **/.env.* **/*.pem **/*.key +**/*.p8 **/lz-data/ **/lz-gateway-data/ diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ae8fba3..82c933c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -113,6 +113,16 @@ jobs: persist-credentials: false - run: bash relay/deploy/smoke-test.sh + # The push gateway's image: builds, starts read-only as its own user, + # keeps its keys private, answers (gateway/smoke-test.sh). + gateway-image: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - run: bash gateway/smoke-test.sh + # Advisories, licenses, banned crates and features (including ohttp's # nss and unsafe-print-secrets), and sources. Policy: deny.toml. cargo-deny: diff --git a/.github/workflows/images.yml b/.github/workflows/images.yml index 23d5aa1..f235c39 100644 --- a/.github/workflows/images.yml +++ b/.github/workflows/images.yml @@ -1,8 +1,10 @@ -# Publishes the self-hosting kit's images (deploy/DESIGN.md, "Releases") -# and the relay's (relay/README.md): +# Publishes the self-hosting kit's images (deploy/DESIGN.md, "Releases"), +# the relay's (relay/README.md) and the reference push gateway's +# (gateway/README.md): # ghcr.io/principlezerolabs/lantern-zero-server # ghcr.io/principlezerolabs/lantern-zero-tor # ghcr.io/principlezerolabs/lantern-zero-relay +# ghcr.io/principlezerolabs/lantern-zero-gateway # for linux/amd64 and linux/arm64, each built on a native runner, with an # SBOM and provenance attached, and signed with cosign keyless (Sigstore, # through this workflow's GitHub identity). Runs on version tags (v*) and @@ -31,7 +33,7 @@ jobs: strategy: fail-fast: true matrix: - image: [server, tor, relay] + image: [server, tor, relay, gateway] arch: [amd64, arm64] include: - arch: amd64 @@ -47,6 +49,9 @@ jobs: - image: relay context: . file: relay/Dockerfile + - image: gateway + context: . + file: gateway/Dockerfile steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: @@ -97,7 +102,7 @@ jobs: id-token: write strategy: matrix: - image: [server, tor, relay] + image: [server, tor, relay, gateway] env: IMAGE: ghcr.io/principlezerolabs/lantern-zero-${{ matrix.image }} steps: diff --git a/RELEASING.md b/RELEASING.md index 7bebc4a..63d17b6 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,9 +1,10 @@ # Releasing A release is a version tag on `main`. The tag publishes the self-hosting -kit's signed images and the relay's (`.github/workflows/images.yml`); -the Compose files then pin their digests. The Rust crates aren't -published (`publish = false`). +kit's signed images, the relay's and the reference push gateway's +(`.github/workflows/images.yml`); the Compose files then pin their +digests. The gateway has no Compose file: vendors pin it themselves. The +Rust crates aren't published (`publish = false`). Updates are opt-in for self-hosters, because the server holds viewing keys for anyone who turns on scanning (`deploy/DESIGN.md`, "Releases"). So @@ -69,13 +70,15 @@ docker buildx imagetools inspect ghcr.io/principlezerolabs/lantern-zero-server@s ``` `imagetools inspect` should list `linux/amd64` and `linux/arm64`. Do the -same for `lantern-zero-tor` and `lantern-zero-relay`. Then add the full +same for `lantern-zero-tor`, `lantern-zero-relay` and +`lantern-zero-gateway`. Then add the full `…@sha256:` references, and the verify command, to the release notes' "Images" section. The packages must be public for self-hosters to pull them (the organization's package settings on GitHub; once per package, so once -more for `lantern-zero-relay` after the first release that has it). +more for `lantern-zero-gateway` after v0.1.3, the first release that +has it). ## 5. Pin the images, then publish the notes diff --git a/gateway/Dockerfile b/gateway/Dockerfile new file mode 100644 index 0000000..b829832 --- /dev/null +++ b/gateway/Dockerfile @@ -0,0 +1,33 @@ +# syntax=docker/dockerfile:1 +# The lz-gateway image (gateway/README.md). Build from the repository root: +# docker build -f gateway/Dockerfile -t lantern-zero/gateway:local . +# Base images are pinned by digest, the same ones as deploy/server.Dockerfile +# and relay/Dockerfile; bump them together. + +# rust:1.95.0-slim-trixie, the same toolchain as rust-toolchain.toml. +FROM rust@sha256:e14e87345b4d5964ddcc3491d27ee046a0f23820f340c3c1e24da6880141f7c0 AS build +# Use the image's toolchain as is: rust-toolchain.toml would make rustup +# download fmt and clippy, which a release build doesn't need. +ENV RUSTUP_TOOLCHAIN=1.95.0 \ + CARGO_TERM_COLOR=never +WORKDIR /src +COPY . . +RUN --mount=type=cache,target=/usr/local/cargo/registry \ + --mount=type=cache,target=/src/target \ + cargo build --release --locked -p lz-gateway \ + && install -D -m 0755 target/release/lz-gateway /out/lz-gateway \ + && install -d -m 0700 /out/data + +# gcr.io/distroless/cc-debian13:nonroot: glibc and libgcc, no shell, +# runs as uid 65532. The gateway's only state is data_dir (sealing keys +# and the revocation list): mount a volume at /var/lib/lz-gateway (a +# named volume takes the image's owner, 65532, and mode 0700; a host +# directory must have them), and the config and the APNs and FCM +# credentials read-only. The root file system can be read-only. +FROM gcr.io/distroless/cc-debian13@sha256:08476c244888bfb425bae1ae4dd7c17f093e972aab8426883d97f3c6f280f7c1 +COPY --from=build /out/lz-gateway /usr/local/bin/lz-gateway +COPY --from=build --chown=65532:65532 /out/data /var/lib/lz-gateway +USER 65532:65532 +EXPOSE 8090 +ENTRYPOINT ["/usr/local/bin/lz-gateway"] +CMD ["/etc/lz-gateway/config.toml"] diff --git a/gateway/README.md b/gateway/README.md index f1f0a7a..5f82d73 100644 --- a/gateway/README.md +++ b/gateway/README.md @@ -103,6 +103,26 @@ minutes. FCM uses a service account (`gcp_auth`). cargo run -p lz-gateway -- gateway/examples/config.toml ``` +Releases publish a signed image, `ghcr.io/principlezerolabs/lantern-zero-gateway` +(linux/amd64 and linux/arm64; `RELEASING.md` says how to verify one). It +runs as uid 65532 with config at `/etc/lz-gateway/config.toml`: + +```sh +docker run --read-only --cap-drop ALL --security-opt no-new-privileges:true \ + -v /srv/gateway/config.toml:/etc/lz-gateway/config.toml:ro \ + -v /srv/gateway/secrets:/etc/lz-gateway/secrets:ro \ + -v lz-gateway-data:/var/lib/lz-gateway \ + ghcr.io/principlezerolabs/lantern-zero-gateway@sha256: +``` + +with `listen = "0.0.0.0:8090"`, `data_dir = "/var/lib/lz-gateway"` and +the credential paths under `/etc/lz-gateway/secrets/`, readable by uid +65532. A named volume gets the right owner and mode by itself; a host +directory must be owned by 65532, mode 0700. Back it up: it holds the +sealing keys. Put TLS, and a per-address limit on `/v0/subscriptions` +(see "Not yet"), in front. `gateway/smoke-test.sh` builds the image and +checks it this way (CI runs it). + ### Rotating the sealing key ```sh diff --git a/gateway/smoke-test.sh b/gateway/smoke-test.sh new file mode 100755 index 0000000..938ed7b --- /dev/null +++ b/gateway/smoke-test.sh @@ -0,0 +1,82 @@ +#!/usr/bin/env bash +# Builds the gateway image (gateway/Dockerfile) and checks it: it starts +# with a read-only root as uid 65532, makes its sealing key in a named +# volume with mode 0600, rejects bad requests, and logs nothing about +# them. The APNs key is a throwaway made here; nothing reaches Apple. +# +# bash gateway/smoke-test.sh # from anywhere in the repository +set -euo pipefail +cd "$(dirname "$0")/.." + +IMAGE=${LZ_GATEWAY_IMAGE:-lantern-zero/gateway:smoke} +NAME=lz-gateway-smoke +VOLUME=lz-gateway-smoke-data +PORT=${PORT:-18090} +WORK=$(mktemp -d) +cleanup() { + docker rm -f "$NAME" >/dev/null 2>&1 || true + docker volume rm "$VOLUME" >/dev/null 2>&1 || true + rm -rf "$WORK" +} +trap cleanup EXIT +fail() { echo "FAIL: $*"; docker logs "$NAME" 2>&1 | tail -20 || true; exit 1; } + +if [ -z "${LZ_GATEWAY_IMAGE:-}" ]; then + docker build -q -f gateway/Dockerfile -t "$IMAGE" . >/dev/null +fi + +mkdir -p "$WORK/secrets" +openssl ecparam -name prime256v1 -genkey -noout | + openssl pkcs8 -topk8 -nocrypt >"$WORK/secrets/apns-key.p8" +chmod 0755 "$WORK/secrets" && chmod 0644 "$WORK/secrets/apns-key.p8" +cat >"$WORK/config.toml" <<'TOML' +listen = "0.0.0.0:8090" +public_origin = "https://push.example.test" +data_dir = "/var/lib/lz-gateway" + +[apns] +team_id = "ABCDE12345" +key_id = "KEY1234567" +key_path = "/etc/lz-gateway/secrets/apns-key.p8" +topic = "app.example.wallet" +sandbox = true +TOML +chmod 0644 "$WORK/config.toml" + +docker volume rm "$VOLUME" >/dev/null 2>&1 || true +docker run -d --name "$NAME" \ + --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges:true \ + -p "127.0.0.1:$PORT:8090" \ + -v "$WORK/config.toml:/etc/lz-gateway/config.toml:ro" \ + -v "$WORK/secrets:/etc/lz-gateway/secrets:ro" \ + -v "$VOLUME:/var/lib/lz-gateway" \ + "$IMAGE" >/dev/null + +for _ in $(seq 1 30); do + docker logs "$NAME" 2>&1 | grep -q serving && break + [ "$(docker inspect -f '{{.State.Running}}' "$NAME")" = true ] || fail "exited" + sleep 1 +done +docker logs "$NAME" 2>&1 | grep -q serving || fail "never started" + +[ "$(docker inspect -f '{{.Config.User}}' "$NAME")" = "65532:65532" ] || fail "not uid 65532" + +# The sealing key: in the volume, owned by the gateway's user, mode 0600. +# busybox:1.37 +BUSYBOX=busybox@sha256:a7dbc319b1438115a207e11930dc4bb3e643dcb3ec0bdd694bb36cd8fad289ec +perms=$(docker run --rm -v "$VOLUME:/d:ro" "$BUSYBOX" stat -c '%u %a' /d/endpoint-keys) \ + || fail "no endpoint-keys in the volume" +[ "$perms" = "65532 600" ] || fail "endpoint-keys is '$perms', want '65532 600'" + +code() { curl -s -o /dev/null -w '%{http_code}' "$@"; } +[ "$(code -X POST "http://127.0.0.1:$PORT/v0/subscriptions" -H 'content-type: application/json' \ + -d '{"platform":"apns","token":"zz","server_key":"x"}')" = 400 ] || fail "bad token not 400" +[ "$(code -X POST "http://127.0.0.1:$PORT/wp/not-an-endpoint" -H 'TTL: 60' \ + -H 'content-encoding: aes128gcm' --data-binary x)" = 404 ] || fail "unknown endpoint not 404" + +# Nothing from the requests in the log. +if docker logs "$NAME" 2>&1 | grep -E 'not-an-endpoint|"zz"|server_key'; then + fail "request data in the log" +fi + +echo "gateway image OK"