diff --git a/Dockerfile.local b/Dockerfile.local index e23c73e..3fe1b30 100644 --- a/Dockerfile.local +++ b/Dockerfile.local @@ -6,9 +6,9 @@ ARG RUNTIME_IMAGE=debian:bookworm-20260112-slim@sha256:56ff6d36d4eb3db13a741b342 FROM ${RUST_IMAGE} AS builder WORKDIR /build -# These named contexts are supplied by the sibling Locks Compose project. The -# Paykit contexts are crate directories, so the paykit-rs repository needs no -# Docker-owned files and its workspace target directory is never transferred. +# These named contexts are supplied by the calling build or Compose project. +# The Paykit contexts are crate directories, so the paykit-rs repository needs +# no Docker-owned files and its workspace target directory is never transferred. RUN --mount=from=paykit-lib,target=/contexts/paykit-lib,ro \ --mount=from=paykit-sdk,target=/contexts/paykit-sdk,ro \ --mount=from=locks,target=/contexts/locks,ro \ diff --git a/README.md b/README.md index b4a8f3e..5778591 100644 --- a/README.md +++ b/README.md @@ -127,7 +127,10 @@ Startup fails before bind if configuration, secrets, PostgreSQL, migrations, aut ### Local Locks demo image -`Dockerfile.local` packages this repository for sibling Locks Compose stack. It consumes checked-out Paykit Rust and Locks trees through named BuildKit contexts, then produces unprivileged local image containing server and helper binaries. +`Dockerfile.local` packages this repository for the Locks Compose stack. It +accepts pinned public Git sources or deliberate local-worktree overrides through +named BuildKit contexts, then produces an unprivileged local image containing +the server and helper binaries. Build command, image contract, source-rewrite behavior, and generated config contract live in [`docs/local-locks-demo.md`](docs/local-locks-demo.md). diff --git a/docs/local-locks-demo.md b/docs/local-locks-demo.md index abdfe60..2973e0a 100644 --- a/docs/local-locks-demo.md +++ b/docs/local-locks-demo.md @@ -1,10 +1,29 @@ # Local Locks demo image -`Dockerfile.local` packages Paykit Server for sibling Locks Compose stack. It is local/demo packaging, not production image. +`Dockerfile.local` packages Paykit Server for the Locks Compose stack. It is local/demo packaging, not a production image. -## Build +## Build from public pinned sources -Build from this repository with checked-out Paykit Rust and Locks source trees supplied as named BuildKit contexts: +From a fresh anonymous clone of this repository, build with the exact Paykit +Rust and Locks revisions pinned in `Cargo.toml`: + +```bash +docker buildx build --load \ + --build-context paykit-lib='https://github.com/pubky/paykit-rs.git#52a852995bfc457b78d32f5a45f6741766a89bba:paykit-lib' \ + --build-context paykit-sdk='https://github.com/pubky/paykit-rs.git#52a852995bfc457b78d32f5a45f6741766a89bba:paykit-sdk' \ + --build-context locks='https://github.com/pubky/locks.git#df5ea1b6d8dcdec3a9b5a915c3f57bca69d75c8a' \ + -f Dockerfile.local \ + -t paykit-server:local . +``` + +These contexts are anonymously reachable and reproducible. Update the URLs +together with the corresponding `Cargo.toml` pins; exact dependency-pin matches +make source drift fail closed. + +## Build from local worktrees + +For coordinated development, override the named contexts with local source +trees. This mode intentionally includes uncommitted source edits: ```bash docker buildx build --load \ @@ -15,7 +34,9 @@ docker buildx build --load \ -t paykit-server:local . ``` -Build uses exact local source-tree contents, including uncommitted source edits. Crate-level `paykit-lib` and `paykit-sdk` contexts avoid transferring Paykit Rust workspace target directory and require no Docker files in that repository. Locks context must exist and applies its existing source-tree exclusions. +Crate-level `paykit-lib` and `paykit-sdk` contexts avoid transferring the Paykit +Rust workspace target directory and require no Docker-owned files in that +repository. The Locks context applies its existing source-tree exclusions. Builder runs [`scripts/prepare-local-docker-sources.sh`](../scripts/prepare-local-docker-sources.sh) against copied manifests to resolve `paykit-lib`, `paykit-sdk`, and `locks-core` from named contexts. Committed Git dependency declarations and lockfile remain unchanged. No SSH agent or Cargo credentials are mounted. Exact dependency-pin matches make source drift fail closed. @@ -29,11 +50,11 @@ Final pinned Debian image: - adds CA certificates and three application binaries to pinned runtime base; - contains no source tree, Cargo cache, runnable config, DB credentials, or application secrets. -Supply `PAYKIT_CONFIG`, `PAYKIT_DATABASE_URL`, and `PAYKIT_MASTER_KEY` at runtime. Mount generated ignored local config. Sibling Compose definition owns mounts, env values, infrastructure image pins, and helper command overrides. +Supply `PAYKIT_CONFIG`, `PAYKIT_DATABASE_URL`, and `PAYKIT_MASTER_KEY` at runtime. Mount generated ignored local config. The calling Compose definition owns mounts, environment values, infrastructure image pins, and helper command overrides. ## Generated local config contract -Sibling Locks orchestration generates `.local/paykit-server/config.toml` only after local Lock Server identity exists. Directory is Git-ignored. It must replace deliberately invalid `` token below with exact canonical `pubky...` value exposed by Lock Server as `credentials.lock_server_public_key`. This block is not runnable config. +Locks orchestration generates `.local/paykit-server/config.toml` only after the local Lock Server identity exists. The directory is Git-ignored. It must replace the deliberately invalid `` token below with the exact canonical `pubky...` value exposed by Lock Server as `credentials.lock_server_public_key`. This block is not runnable config. ```toml [http] diff --git a/docs/plans/0001-receiver-only-prototype-design.md b/docs/plans/0001-receiver-only-prototype-design.md index 909fa36..583bf43 100644 --- a/docs/plans/0001-receiver-only-prototype-design.md +++ b/docs/plans/0001-receiver-only-prototype-design.md @@ -20,8 +20,8 @@ Only **EXPLICIT**, **AUTHORITATIVE SOURCE**, and **CONSTRAINT** entries may driv The user designated these as authoritative for Locks Server ↔ Paykit Server HTTP behavior: -- `../../Pubky/locks/docs/ADRs/0020-locks-paykit-v1-integration-boundary.md` -- matching behavior in `../../Pubky/locks/locks-server/src/paykit_http_client.rs` +- [Locks ADR 0020](https://github.com/pubky/locks/blob/df5ea1b6d8dcdec3a9b5a915c3f57bca69d75c8a/docs/ADRs/0020-locks-paykit-v1-integration-boundary.md) +- matching [Locks Paykit HTTP client](https://github.com/pubky/locks/blob/df5ea1b6d8dcdec3a9b5a915c3f57bca69d75c8a/locks-server/src/paykit_http_client.rs) ### Product flow @@ -40,8 +40,8 @@ Current `../paykit-rs` code/specifications define dependency behavior. They are **EXPLICIT**: - Canonical Locks creator, reader, bundle, addressed lock-resource identifiers, - and Paykit-payment policy validation use `locks-core` pinned at revision - `06bc63c4b5ff7df194f26f3f3fecb8dab4d28995`; Paykit Server does not duplicate + and Paykit-payment policy validation use `locks-core` pinned at public revision + `df5ea1b6d8dcdec3a9b5a915c3f57bca69d75c8a`; Paykit Server does not duplicate their parsing, canonicalization, or policy grammar. ## Actors and key boundaries diff --git a/docs/plans/0002-receiver-only-prototype-implementation.md b/docs/plans/0002-receiver-only-prototype-implementation.md index 2bf4a64..4e7b547 100644 --- a/docs/plans/0002-receiver-only-prototype-implementation.md +++ b/docs/plans/0002-receiver-only-prototype-implementation.md @@ -6,12 +6,12 @@ **Architecture:** A virtual Rust workspace contains one server crate and one black-box E2E crate. `paykit-server` owns HTTP, application workflows, encrypted PostgreSQL persistence, and worker orchestration; it calls `paykit-sdk` rather than recreating Paykit protocols. Creator authority, one BIP84 account xpub/account index, address allocation, receiver Noise key, and SDK state are isolated per Creator inside one supported server process. `paykit-server-e2e` starts the real Axum application against PostgreSQL and verifies committed cross-boundary and cross-Creator isolation contracts. -**Tech Stack:** Rust edition 2024 (MSRV 1.91.1), Tokio, Axum, SQLx/PostgreSQL, `paykit-sdk`/`paykit-lib` pinned to inspected `paykit-rs` commit `81fd0e5124aac1fd782811fd968109a5972cd323`, XChaCha20-Poly1305, HKDF-SHA256, Ed25519, Electrum client. +**Tech Stack:** Rust edition 2024 (MSRV 1.91.1), Tokio, Axum, SQLx/PostgreSQL, `paykit-sdk`/`paykit-lib` pinned to inspected `paykit-rs` commit `52a852995bfc457b78d32f5a45f6741766a89bba`, XChaCha20-Poly1305, HKDF-SHA256, Ed25519, Electrum client. **Authoritative requirements:** - `docs/plans/0001-receiver-only-prototype-design.md` -- `../../Pubky/locks/docs/ADRs/0020-locks-paykit-v1-integration-boundary.md` -- Matching Locks behavior in `../../Pubky/locks/locks-server/src/paykit_http_client.rs` +- [Locks ADR 0020](https://github.com/pubky/locks/blob/df5ea1b6d8dcdec3a9b5a915c3f57bca69d75c8a/docs/ADRs/0020-locks-paykit-v1-integration-boundary.md) +- Matching [Locks Paykit HTTP client](https://github.com/pubky/locks/blob/df5ea1b6d8dcdec3a9b5a915c3f57bca69d75c8a/locks-server/src/paykit_http_client.rs) **Hard boundary:** Do not implement unsupported Paykit wire/Encrypted-Link behavior locally. Delegate it to the pinned `paykit-sdk` dependency. diff --git a/docs/plans/0004-local-locks-compose-integration.md b/docs/plans/0004-local-locks-compose-integration.md index 857f23d..d8df6e9 100644 --- a/docs/plans/0004-local-locks-compose-integration.md +++ b/docs/plans/0004-local-locks-compose-integration.md @@ -8,6 +8,12 @@ **Tech stack:** Rust 1.91.1, Axum, `paykit-sdk`, PostgreSQL/SQLx, Docker multi-stage builds, Pubky static testnet, Bitcoin Core regtest, BDK Electrum. +**Publication note:** The original peer implementation plan was intentionally +not included in the fresh public Locks history. The public cross-service +contract is [Locks ADR 0020](https://github.com/pubky/locks/blob/df5ea1b6d8dcdec3a9b5a915c3f57bca69d75c8a/docs/ADRs/0020-locks-paykit-v1-integration-boundary.md). +Public image builds use anonymous pinned Git contexts; sibling worktrees remain +an explicit local-development override. + --- ## Requirement provenance @@ -26,12 +32,12 @@ ### AUTHORITATIVE SOURCE -- `../paykit-rs/specs/pubky-auth-companion-claims.md`. -- `../paykit-rs/paykit-sdk/src/pubky_session/companion_claim.rs`. +- [Paykit companion-claim specification](https://github.com/pubky/paykit-rs/blob/52a852995bfc457b78d32f5a45f6741766a89bba/specs/pubky-auth-companion-claims.md). +- [Paykit SDK companion-claim implementation](https://github.com/pubky/paykit-rs/blob/52a852995bfc457b78d32f5a45f6741766a89bba/paykit-sdk/src/pubky_session/companion_claim.rs). - `paykit-server/src/bitkit_claim.rs` for exact `watch-only-account-v1` payload and receiver validation. - `paykit-server/src/real_setup.rs` for setup commit ordering and xpub validation. - `README.md` and `config/paykit-server.example.toml` for supported runtime/config behavior. -- Peer plan: `../../Pubky/locks/docs/plans/0042-local-paykit-integration-demo.md`. +- Public peer contract: [Locks ADR 0020](https://github.com/pubky/locks/blob/df5ea1b6d8dcdec3a9b5a915c3f57bca69d75c8a/docs/ADRs/0020-locks-paykit-v1-integration-boundary.md). ### CONSTRAINTS OBSERVED IN CURRENT CODE @@ -126,7 +132,7 @@ No implementation task may invent an answer to these gates. **Files:** - Create/Modify: `docs/plans/0004-local-locks-compose-integration.md` -- Review: `../../Pubky/locks/docs/plans/0042-local-paykit-integration-demo.md` +- Review: public [Locks ADR 0020](https://github.com/pubky/locks/blob/df5ea1b6d8dcdec3a9b5a915c3f57bca69d75c8a/docs/ADRs/0020-locks-paykit-v1-integration-boundary.md) **Steps:** 1. Resolve all gates one question at a time. @@ -265,8 +271,12 @@ No implementation task may invent an answer to these gates. cargo test --workspace cargo clippy --workspace --all-targets -- -D warnings cargo fmt --check -docker buildx build --build-context paykit-lib=../paykit-rs/paykit-lib --build-context paykit-sdk=../paykit-rs/paykit-sdk --build-context locks=../../Pubky/locks -f Dockerfile.local -t paykit-server:local . +docker buildx build --load \ + --build-context paykit-lib='https://github.com/pubky/paykit-rs.git#52a852995bfc457b78d32f5a45f6741766a89bba:paykit-lib' \ + --build-context paykit-sdk='https://github.com/pubky/paykit-rs.git#52a852995bfc457b78d32f5a45f6741766a89bba:paykit-sdk' \ + --build-context locks='https://github.com/pubky/locks.git#df5ea1b6d8dcdec3a9b5a915c3f57bca69d75c8a' \ + -f Dockerfile.local -t paykit-server:local . git diff --check ``` -The sibling Locks plan must add executable wrapper commands that load ignored generated credentials and run explicit `TEST_DATABASE_URL` suites plus the Compose smoke without printing secrets. +The corresponding Locks integration must add executable wrapper commands that load ignored generated credentials and run explicit `TEST_DATABASE_URL` suites plus the Compose smoke without printing secrets.