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
5 changes: 5 additions & 0 deletions docs/reference/remote-authority-task-service-v0.md
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,11 @@ intent can then query retained historical receipts with that new binding.

## Running the candidate

For a local PostgreSQL 16 server and HTTPS gateway, build the
[self-hosted Compose bundle](../../examples/coordination/remote-authority-compose/README.en.md)
from a pinned commit. The bundle boots an isolated starter Goal with two
independent client credentials. [简体中文](../../examples/coordination/remote-authority-compose/README.md)

Use the repository's qualified Node runtime and `npm ci --ignore-scripts`.
Provision an isolated PostgreSQL authority schema/head using the existing
provider administration path. The listener never installs schemas or seeds
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
*
!loopx-source.tar.gz
!Dockerfile
!provision.mjs
!launch.mjs
14 changes: 14 additions & 0 deletions examples/coordination/remote-authority-compose/Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
FROM public.ecr.aws/docker/library/node:24.21.0-bookworm@sha256:3d27e5c11e5786e309ec3e03f93ae536eb36e6e5eb3714d5eb3300a36157add0
ARG LOOPX_REVISION
ARG LOOPX_SOURCE_SHA256
WORKDIR /opt/loopx
LABEL org.opencontainers.image.source="https://github.com/loopx-project/loopx" \
org.opencontainers.image.revision="${LOOPX_REVISION}"
COPY loopx-source.tar.gz /tmp/loopx-source.tar.gz
RUN printf '%s %s\n' "$LOOPX_SOURCE_SHA256" /tmp/loopx-source.tar.gz | sha256sum -c - \
&& tar -xzf /tmp/loopx-source.tar.gz \
&& rm /tmp/loopx-source.tar.gz \
&& command -v openssl \
&& npm ci --ignore-scripts --no-audit --no-fund --include=dev
COPY provision.mjs launch.mjs ./
USER 1000:1000
58 changes: 58 additions & 0 deletions examples/coordination/remote-authority-compose/README.en.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Self-hosted LoopX coordination

Extract a built bundle on a machine with Docker Engine and Compose, then run the commands below. The first start uses container registries and npm. Select a free loopback port with `LOOPX_PORT`, which defaults to 8443.

```sh
./start.sh
./client.sh a read
./client.sh b read
./client.sh reader read
```

Two trusted writers have distinct credentials and can hand off the same starter Todo. An additional `reader` has its own credential and can read only the allowed starter task. The first start provisions PostgreSQL authority state, a private CA and clients. Later starts reuse the task, store identity and policies from the volumes. The database runs on an internal network.

Use `./client.sh a descriptor` to get the tenant, Goal, actor and store identity. Pass the request on standard input to `./client.sh a request`. When a reply is lost, keep the original request and `request_id` and pass them to `./client.sh a recover`.

A remote client can forward the server's loopback port over SSH and use the same revision of `remote-authority-client.ts` with `--ca`. Export the CA with `./client.sh a ca` and deliver the client's `credential` and `request.json` privately from its volume. The CLI reads the credential from `LOOPX_AUTHORITY_CREDENTIAL`. [Gateway requests and recovery](https://github.com/loopx-project/loopx/blob/main/docs/reference/remote-authority-task-service-v0.md)

Both TLS gateways publish loopback ports: trusted writers use `LOOPX_PORT` (8443 by default), while the scoped reader uses `LOOPX_READ_PORT` (8444 by default). Its private policy binds the exact Goal lifetime, Todo and original creation/binding receipt. Unlisted resources are denied. Snapshots return only allowed state, without notes, lease keys or a global cursor. Todo access does not authorize historical operation receipts.

The trusted writer endpoint retains v0 scope/operation grants; a/b can read other tasks in the same scope. The v1 resource ACL supports read/snapshot, not resource-scoped writes. Give observers only the reader credential and read port. Both listeners reuse the existing service and restricted database role. Reader isolation does not qualify resource isolation for writers. TLS covers client-to-gateway connections; database connections use the isolated backend network.

## Build and qualify

Run this from the reviewed template checkout. Supply the complete Git commit to use for the gateway build.

```sh
python3 examples/coordination/remote-authority-compose/build_bundle.py \
--source-revision "$(git rev-parse HEAD)" --output /tmp/loopx-authority.tar.gz
```

The same source commit and template contents produce the same archive. The bundle contains `LICENSE`, `NOTICE`, the source digest and pinned image manifests. Docker verifies the digest before unpacking the source. Keep generated bundles, credentials, data and backups in their respective release or runtime storage.

The source revision must include scoped v1 reads (#8861). Qualify from an unpacked bundle on a disposable Docker host with a unique project name and two free loopback ports. On amd64, verify the architecture of the host and running services. Time cold and cached starts through image pull, build, readiness and client reads. Check that PostgreSQL has no published port, clients have no route to the backend network and they have no database credential.

Run the rehearsal from the repository. It creates a temporary project, exercises writer claim, expiry, takeover, original receipt recovery and replay after restart for creation and completion, plus reader filtering, write denial, persistent revocation and missing/malformed policy refusal, then removes its own containers and volumes.

```sh
node examples/coordination/remote-authority-compose/rehearse.mjs /path/to/unpacked-bundle
```

Compose limits CPU, memory, processes and retained logs. Check the Docker data disk and current load before a shared-host trial. Use dedicated projects, ports, networks and volumes. Tests with two local clients qualify the protocol. Qualifying two physical hosts requires a client on the second host.

## Back up, restore and rotate

```sh
./state.sh backup /absolute/path/to/new-backup
./start.sh
COMPOSE_PROJECT_NAME=loopx-restored ./state.sh restore /absolute/path/to/new-backup
COMPOSE_PROJECT_NAME=loopx-restored LOOPX_PORT=8445 LOOPX_READ_PORT=8446 ./start.sh
```

Backup stops the project and captures its database and credential volumes together. Keep backups encrypted and access-controlled. Restore verifies the digests and bundle version, and requires a new project with no existing target volumes. Read back tasks and original operation receipts before switching clients, and stop admitting requests on the old project first.

- Revoke access by atomically replacing `policy.json` in the relevant gateway volume: `reader-gateway` for scoped reads and `gateway` for trusted writes. Removing a resource entry or credential rejects the next request. Replacing a running v1 listener's policy with v0 cannot downgrade its permissions. Rotate high-entropy credentials together with their private policy digest and client file. Earlier backups still contain earlier credentials.
- The generated leaf certificate lasts 397 days. Reissue it before expiry with the CA in `pg-admin` and the original SANs. Before switching, verify the new certificate with the existing CA on the clients and confirm their clocks have reached its `notBefore` time. Replace the matching `cert.pem` and `key.pem` in both the `gateway` and `reader-gateway` volumes. With the same Compose project settings, run `docker compose restart gateway reader-gateway`. Use `docker compose ps gateway reader-gateway` to confirm both services are healthy, then verify both TLS endpoints and read back the task with `./client.sh a read`, `./client.sh b read` and `./client.sh reader read`. Distribute trust before rotating a CA.
- Back up before changing database credentials or versions. Rehearse migration and rollback in an isolated project. Update database roles and credential files together. Follow PostgreSQL's supported migration procedure across major versions.

[简体中文](README.md)
58 changes: 58 additions & 0 deletions examples/coordination/remote-authority-compose/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# LoopX 远程协同自托管

在装有 Docker Engine 和 Compose 的机器上解压构建好的包,进入目录运行。首次启动需要访问镜像仓库和 npm。选一个空闲的回环端口,默认使用 8443。

```sh
./start.sh
./client.sh a read
./client.sh b read
./client.sh reader read
```

两个可信写客户端拥有不同凭据,可以交接同一个示例任务。额外的 `reader` 使用独立凭据,只能读取获准的示例任务。首次启动创建 PostgreSQL 权威库、私有 CA 和客户端。重复启动沿用卷里的任务、存储身份和撤权策略。数据库在内部网络中运行。

用 `./client.sh a descriptor` 取得请求的租户、Goal、Actor 和存储实例。把请求放在标准输入上,用 `./client.sh a request` 执行。发送超时后,保留原请求及 `request_id`,通过 `./client.sh a recover` 查询回执。

远端客户端可用 SSH 将网关的回环端口转发到本机,再用同一版本的 `remote-authority-client.ts` 和 `--ca` 连接。管理员可导出 `./client.sh a ca`,并私下交付对应客户端卷中的 `credential` 和 `request.json`。客户端通过 `LOOPX_AUTHORITY_CREDENTIAL` 接收凭据。 [网关请求与重试说明(英文)](https://github.com/loopx-project/loopx/blob/main/docs/reference/remote-authority-task-service-v0.md)

两个 TLS 网关都只发布回环端口:可信写客户端使用 `LOOPX_PORT`(默认 8443),受限读者使用 `LOOPX_READ_PORT`(默认 8444)。`reader` 的私有策略绑定当前 Goal 实例、具体 Todo 及其原始创建/绑定回执;未列入的资源默认拒绝。snapshot 仅返回获准状态,不含 note、租约密钥或全局游标。读授权不授予历史操作回执访问。

可信写入口保留 v0 的范围和操作授权,a/b 可读取同范围任务;当前 v1 资源 ACL 只支持 read/snapshot,不能提供资源级写隔离。向观察者仅交付 `reader` 的凭据和只读端口。两入口共用原服务和受限数据库角色,不能将读者隔离表述为写客户端也被资源 ACL 限制。客户端到网关使用 TLS,数据库连接走隔离 backend 网络。

## 构建和验收

从经审阅的模板 checkout 运行。选择用于构建网关的完整 Git 提交。

```sh
python3 examples/coordination/remote-authority-compose/build_bundle.py \
--source-revision "$(git rev-parse HEAD)" --output /tmp/loopx-authority.tar.gz
```

同一源码提交和模板内容生成相同的归档。归档内含 `LICENSE`、`NOTICE`、源码摘要及固定镜像清单。Docker 构建前会校验源码摘要。生成物、运行凭据、数据库和备份应存放在各自的发布或运行位置。

源码版本须包含 scoped v1 读取实现(#8861)。在专用测试 Docker 环境中解压验证,使用唯一的 Compose 项目名和两个空闲回环端口。在 amd64 主机上验证本机架构和实际运行架构。冷启动与缓存启动分别记录镜像拉取、构建、就绪与客户端首次读回时间。确认数据库端口未发布,客户端无法访问 backend 网络,网关不向客户端提供数据库凭据。

从仓库运行下列演练。它会创建临时项目,验证写客户端的认领、到期接管、新增任务与完成操作的原回执恢复及重启重放,以及只读客户端的资源过滤、拒写、撤权重启和策略缺失/损坏拒绝,最后清理自己的容器和卷。

```sh
node examples/coordination/remote-authority-compose/rehearse.mjs /path/to/unpacked-bundle
```

Compose 为数据库、网关及辅助容器设置 CPU、内存、进程数和日志轮转。共享主机还需核对 Docker 数据盘空间与已有负载。选择独立项目名、端口、网络和卷。两个同主机容器可以验证协议,跨物理主机资格需从另一台主机连接验证。

## 备份、恢复和轮换

```sh
./state.sh backup /absolute/path/to/new-backup
./start.sh
COMPOSE_PROJECT_NAME=loopx-restored ./state.sh restore /absolute/path/to/new-backup
COMPOSE_PROJECT_NAME=loopx-restored LOOPX_PORT=8445 LOOPX_READ_PORT=8446 ./start.sh
```

备份会停止当前 Compose 项目,保存同一时点的数据库和凭据卷。请将含私钥及数据库凭据的备份放在加密受限的位置。恢复前校验摘要和包版本,并要求新项目的目标卷尚未创建。启动后读回任务和原操作回执,确认旧项目已停止接收请求再切换入口。

- 撤权时原子替换对应网关卷中的 `policy.json`。只读策略位于 `reader-gateway` 卷,写策略位于 `gateway` 卷;撤销资源条目或凭据后下一次请求即拒绝。不能把 v0 策略放到已启动的 v1 监听器来降级权限。轮换密钥须生成新的高熵凭据,同步更新私有策略和客户端凭据。备份也含历史凭据。
- 自动生成的服务叶证书有效期为 397 天。到期前用 `pg-admin` 中的 CA 续签,保留原 SAN。切换前在客户端用原 CA 校验新证书,确认各客户端时钟已到新证书的 `notBefore` 时间。将配对的 `cert.pem` 和 `key.pem` 更新到 `gateway` 与 `reader-gateway` 两个卷中。沿用同一 Compose 项目配置运行 `docker compose restart gateway reader-gateway`。用 `docker compose ps gateway reader-gateway` 确认两个服务均已就绪(`healthy`),再校验两个 TLS 入口,再用 `./client.sh a read`、`./client.sh b read` 和 `./client.sh reader read` 读回任务。更换 CA 时提前分发新信任。
- 更新 PostgreSQL 口令或版本前先备份,在隔离项目演练迁移和回退。同步修改数据库角色与对应凭据文件。PostgreSQL 跨大版本需使用其正式迁移流程。

[English](README.en.md)
102 changes: 102 additions & 0 deletions examples/coordination/remote-authority-compose/build_bundle.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
#!/usr/bin/env python3
"""Build a source-pinned, reproducible LoopX self-hosting bundle."""

import argparse
import gzip
import hashlib
import io
import os
from pathlib import Path
import re
import subprocess
import tarfile
import tempfile


TEMPLATE = Path(__file__).resolve().parent
REPOSITORY = TEMPLATE.parents[2]
BUNDLE_NAME = "loopx-remote-authority-compose"
SOURCE_PATHS = (
"LICENSE",
"NOTICE",
"package.json",
"package-lock.json",
"examples/coordination/remote-authority-client.ts",
"examples/coordination/remote-authority-service.ts",
"loopx/control_plane",
)
BUNDLE_FILES = (
".dockerignore",
"Dockerfile",
"README.en.md",
"README.md",
"client.sh",
"compose.yaml",
"launch.mjs",
"provision.mjs",
"start.sh",
"state.sh",
)


def git(*args: str) -> bytes:
return subprocess.check_output(["git", *args], cwd=REPOSITORY)


def gzip_archive(data: bytes) -> bytes:
encoded = io.BytesIO()
with gzip.GzipFile(filename="", fileobj=encoded, mode="wb", mtime=0) as compressed:
compressed.write(data)
return encoded.getvalue()


def bundle(revision: str) -> bytes:
source_tar = git("archive", "--format=tar", revision, "--", *SOURCE_PATHS)
source_archive = gzip_archive(source_tar)
source_digest = hashlib.sha256(source_archive).hexdigest()
files = {name: (TEMPLATE / name).read_bytes() for name in BUNDLE_FILES}
image_id = hashlib.sha256(b"".join(
hashlib.sha256(data).digest()
for data in (source_archive, files["Dockerfile"], files["compose.yaml"],
files["provision.mjs"], files["launch.mjs"])
)).hexdigest()
files[".env"] = (
f"LOOPX_REVISION={revision}\nLOOPX_SOURCE_SHA256={source_digest}\n"
f"LOOPX_IMAGE_ID={image_id}\n"
).encode("ascii")
files["loopx-source.tar.gz"] = source_archive
for name in ("LICENSE", "NOTICE"):
files[name] = git("show", f"{revision}:{name}")

archive = io.BytesIO()
with tarfile.open(fileobj=archive, mode="w", format=tarfile.USTAR_FORMAT) as output:
for name, contents in sorted(files.items()):
entry = tarfile.TarInfo(f"{BUNDLE_NAME}/{name}")
entry.size = len(contents)
entry.mode = 0o755 if name.endswith(".sh") else 0o644
output.addfile(entry, io.BytesIO(contents))
return gzip_archive(archive.getvalue())


def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--source-revision", required=True, help="full LoopX Git commit")
parser.add_argument("--output", type=Path, required=True, help="new tar.gz file")
args = parser.parse_args()
if not re.fullmatch(r"[0-9a-f]{40}", args.source_revision):
parser.error("--source-revision must be a full lowercase Git commit SHA")
try:
if git("cat-file", "-t", args.source_revision).strip() != b"commit":
parser.error("--source-revision must identify a commit")
contents = bundle(args.source_revision)
with tempfile.TemporaryDirectory(dir=args.output.parent) as work:
temporary = Path(work) / "bundle.tar.gz"
temporary.write_bytes(contents)
os.link(temporary, args.output)
except (OSError, subprocess.CalledProcessError) as error:
parser.exit(1, f"Could not build bundle: {error}\n")
print(f"{hashlib.sha256(contents).hexdigest()} {args.output}")


if __name__ == "__main__":
main()
10 changes: 10 additions & 0 deletions examples/coordination/remote-authority-compose/client.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
#!/bin/sh
set -eu
case "${1:-}" in
a|b|reader) actor=$1; shift ;;
*) printf '%s\n' "Usage: ./client.sh a|b|reader [read|request|recover|descriptor|ca]" >&2; exit 2 ;;
esac
directory=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
cd "$directory"
[ "$#" -gt 0 ] || set -- read
exec docker compose run --rm --no-deps -T "client-${actor}" "$@"
Loading
Loading