Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
Expand Up @@ -8,5 +8,6 @@ deploy/
**/.env.*
**/*.pem
**/*.key
**/*.p8
**/lz-data/
**/lz-gateway-data/
10 changes: 10 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
13 changes: 9 additions & 4 deletions .github/workflows/images.yml
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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:
Expand Down
13 changes: 8 additions & 5 deletions RELEASING.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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

Expand Down
33 changes: 33 additions & 0 deletions gateway/Dockerfile
Original file line number Diff line number Diff line change
@@ -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"]
20 changes: 20 additions & 0 deletions gateway/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:<digest>
```

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
Expand Down
82 changes: 82 additions & 0 deletions gateway/smoke-test.sh
Original file line number Diff line number Diff line change
@@ -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"
Loading