Feat/paykit payment lock demo by dzdidi · Pull Request #10 · pubky/locks

dzdidi · 2026-08-04T11:47:27Z

Summary

Contract and risk impact

Public API or SDK contract
Persisted data or migration
Authentication, authorization, identity, or secret handling
Payment or entitlement behavior
Runtime, deployment, or observability
No contract/risk impact

Verification

docker compose --file compose.paykit-local-demo.yaml up -d --build

Documentation

Checklist

The change is focused and self-reviewed.
Regression tests were added where practical.
No credentials, identities, private content, payment material, or generated local state are included.
Formatting and relevant tests/lints pass.

* fix: support Bitkit local wallet tests * fix: complete external wallet Paykit demo * chore: use fast Paykit handshake retries * fix: make local wallet E2E startup reliable * fix: hide recovery auth in external wallet mode * fix: use external creator profile for reader setup * examples: validate work locally Signed-off-by: dzdidi <dzdidi@users.noreply.github.com> * docs|examples: improve texts Signed-off-by: dzdidi <dzdidi@users.noreply.github.com> --------- Signed-off-by: dzdidi <dzdidi@users.noreply.github.com> Co-authored-by: dzdidi <dzdidi@users.noreply.github.com>

Copilot

Pull request overview

This PR adds an opt-in local Paykit “payment lock” demonstration stack (Docker Compose + JS demo flows) and updates Locks server/SDK behavior to better support loopback/IP-based local environments and payment-oriented reader/creator flows.

Changes:

Introduces compose.paykit-local-demo.yaml and supporting scripts/Dockerfiles to run a complete local Paykit + Bitcoin regtest + Fulcrum + Pubky testnet + Locks + demos stack.
Updates Locks server + SDK to treat loopback IP domains similarly to localhost (HTTP-port publishing / endpoint rewrite).
Extends the JS/WASM bindings and example demos for payment proof flows, safer local state handling, and stricter static file / logging boundaries.

Reviewed changes

Copilot reviewed 61 out of 61 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
scripts/test-compose-bootstrap.sh	Extends compose bootstrap test to assert a generated public config file.
README.md	Documents Paykit local demo quickstart and updated loopback URLs.
locks-server/src/pkdns.rs	Publishes HTTP port for loopback IP “domains”; adds regression test.
locks-server/src/app_state/test_support.rs	Updates Pubky HTTP client constructor test expectations.
locks-server/src/app_state/pubky_clients.rs	Builds testnet Pubky HTTP client with explicit loopback host and no DHT.
locks-server/src/api/creator_authority.rs	PostMessage connect shell now includes state and simplified error; iframe consumer contract update.
locks-sdk/src/transport.rs	Treats loopback IP endpoint domains like localhost for HTTP-port rewrite; adds test.
locks-sdk/bindings/js/src/viewer.rs	Adds WASM API to return a `Response` for guarded reads; refactors fetch helper.
locks-sdk/bindings/js/src/session.rs	Exposes authenticated creator pubky on JS Session; adds tests.
locks-sdk/bindings/js/src/locks.rs	Parses frontend session response including creator; threads creator into Session.
locks-sdk/bindings/js/scripts/smoke-generated-api.mjs	Updates API smoke expectations for new viewer method.
locks-e2e/tests/legacy_connect_shell_http.rs	Updates E2E assertions for new connect-shell script behavior.
examples/js-sdk/scripts/validate-paykit-compose.mjs	Adds compose model validation for safety boundaries (digest pinning, ports, mounts, users).
examples/js-sdk/scripts/test-paykit-reader-worker.mjs	Adds a worker-level test harness for Paykit reader orchestration and file permissions.
examples/js-sdk/scripts/start-reader-demo-server.mjs	Adds reader worker + status endpoints; tightens static path serving and client log handling.
examples/js-sdk/scripts/start-demo-server.mjs	Adds Paykit-aware creator demo behavior, improved session state handling, and stricter client log handling.
examples/js-sdk/scripts/reset-paykit-demo.mjs	Adds a reset command to clear demo runtime state/volumes while preserving identities/config.
examples/js-sdk/scripts/register-paykit-reader.mjs	Adds bounded input protocol for reader registration step.
examples/js-sdk/scripts/receive-paykit-request.mjs	Adds a standalone “receive” wrapper gated by worker ownership lock.
examples/js-sdk/scripts/publish-creator-profile.mjs	Publishes a minimal public creator profile for reader/Paykit integration.
examples/js-sdk/scripts/prepare-paykit-reader.mjs	Adds a standalone “prepare” wrapper gated by worker ownership lock.
examples/js-sdk/scripts/paykit-companion-auth-compose.sh	Compose wrapper to run Paykit companion auth helper in container.
examples/js-sdk/scripts/lib/pubky.mjs	Adds recovery-file secret extraction helper with explicit free/cleanup.
examples/js-sdk/scripts/lib/paykit-reader-worker.mjs	Implements reader worker orchestration + ownership locking.
examples/js-sdk/scripts/lib/paykit-reader-status.mjs	Adds validated, atomic, owner-only worker/prepared status persistence + browser projection.
examples/js-sdk/scripts/lib/paykit-reader-helper.mjs	Adds bounded helper orchestration and strict parsing/normalization of helper outputs.
examples/js-sdk/scripts/lib/paths.mjs	Expands demo state paths and adds atomic writes + private read helpers.
examples/js-sdk/scripts/lib/creator-static-path.mjs	Adds safe static path resolution (prevents path traversal / symlink escape).
examples/js-sdk/scripts/lib/creator-session-state.mjs	Adds identity-consistent creator session read/write with rotation safety.
examples/js-sdk/scripts/lib/config.mjs	Adds Paykit config, loopback defaults, and paykit compose env validators/config builders.
examples/js-sdk/scripts/init-paykit-compose.mjs	Generates compose secrets/config/env files with strict validation and atomic writes.
examples/js-sdk/scripts/init-config.mjs	Updates config init output path + optional lock-config override.
examples/js-sdk/scripts/homegate-bridge.mjs	Adds local Homegate-compatible signup bridge service.
examples/js-sdk/scripts/generate-paykit-account-tpub.mjs	Adds safe extraction of BIP84 testnet account xpub from Bitcoin Core descriptors.
examples/js-sdk/scripts/electrum-readiness.mjs	Adds protocol-level Fulcrum readiness probe using `server.version`.
examples/js-sdk/scripts/create-user.mjs	Clears role-scoped demo state when regenerating identities.
examples/js-sdk/scripts/authenticate-paykit.mjs	Adds bounded Paykit companion auth wrapper with safe input handling.
examples/js-sdk/README.md	Extensive docs update for Paykit compose demo, boundaries, and manual payment flow.
examples/js-sdk/reader.html	Adds paykit-payment UI section and improves output rendering for images.
examples/js-sdk/reader-flow.js	Adds paykit payment proof submission and guarded read decoding with content-type handling.
examples/js-sdk/paykit-setup.js	Adds Paykit setup iframe request + postMessage acceptance with strict origin/state checks.
examples/js-sdk/package.json	Adds Paykit scripts and expands `check` coverage.
examples/js-sdk/index.html	Updates creator UI labels/fields for paykit-payment lock type.
examples/js-sdk/iframe.html	Updates creator UI labels/fields for paykit-payment lock type.
examples/js-sdk/flows.html	Updates flow descriptions to reflect iframe auth and in-memory session behavior.
examples/js-sdk/creator-lock-policy.js	Centralizes lock policy building for dev-static vs paykit-payment.
examples/js-sdk/creator-identity.js	Adds enforcement of Lock Server creator identity matching demo creator identity.
examples/js-sdk/creator-complete-flow.js	Threads creator identity expectation into connect exchange and allows caller-supplied lockLogic.
examples/js-sdk/app.js	Switches to shared iframe auth implementation.
examples/js-sdk/app-iframe.js	Adds Paykit setup flow, creator identity scoping, and stricter message/client-log handling.
docs/LOCAL_OPERATOR_DEMO.md	Documents the Paykit compose demo as a distinct operator path.
docker/pubky-testnet.Dockerfile	Updates pinned pubky-core commit used for testnet builds.
docker/locks-server-compose-entrypoint.sh	Generates a public Lock Server config file and adds Paykit config section.
docker/js-demo.Dockerfile	Adds JS demo container build with WASM package build stage and bundled native helpers.
docker/bitcoin-bootstrap.sh	Adds regtest chain bootstrapper that mines to height 101.
docker-compose.yml	Updates pinned pubky-core commit argument.
compose.paykit-local-demo.yaml	Adds full Paykit local demo compose stack with safety constraints and health gates.
.github/workflows/check.yml	Installs JS demo deps in CI before running JS/WASM SDK tests.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

        if (res.ok) {{
          try {{
            const {{ state, code }} = await res.json();
            post({{ type: CALLBACK_TYPE, state, code }});
          }} catch (_e) {{


Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Signed-off-by: dzdidi <dzdidi@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 65 out of 65 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

locks-server/src/api/creator_authority.rs:250

The doc comment reads awkwardly: "surfaced as a closed ... message". This looks like a grammatical typo and is confusing about the contract.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

dzdidi · 2026-08-25T17:30:47Z

@ben-kaufman may you please test this one with with bitkit and approve it all good

dzdidi · 2026-08-25T17:31:19Z

@Taewa may you please test this one with with local pubky.app and approve it all good

dzdidi · 2026-08-25T17:32:57Z

once merged, the deployment for e2e testing is next

dzdidi added 5 commits August 4, 2026 08:26

feat(js-sdk): expose authenticated session metadata

2403278

fix(auth): harden iframe callback delivery

0dc4617

feat(demo): add Paykit payment lock workflow

c19125d

feat(compose): add isolated Paykit payment demo

424efa3

docs: document Paykit payment demo workflow

d9edad1

ben-kaufman mentioned this pull request Aug 4, 2026

fix: support Bitkit local wallet tests #11

Merged

10 tasks

dzdidi requested a lite review from Copilot August 25, 2026 11:52

Copilot started reviewing on behalf of dzdidi August 25, 2026 11:53 View session

Copilot AI reviewed Aug 25, 2026

View reviewed changes

dzdidi and others added 5 commits August 25, 2026 10:26

Potential fix for pull request finding

5049103

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

1e5fcc6

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

890f2d6

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

match loopback localhost

6ea078f

Signed-off-by: dzdidi <dzdidi@users.noreply.github.com>

allign docs, fix outputs

d3eac2e

Signed-off-by: dzdidi <dzdidi@users.noreply.github.com>

dzdidi force-pushed the feat/paykit-payment-lock-demo branch from d6e49eb to d3eac2e Compare August 25, 2026 16:47

dzdidi requested a lite review from Copilot August 25, 2026 17:18

Copilot started reviewing on behalf of dzdidi August 25, 2026 17:18 View session

Copilot AI reviewed Aug 25, 2026

View reviewed changes

Comment thread examples/js-sdk/app-iframe.js Outdated

Potential fix for pull request finding

6bd120b

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

dzdidi requested review from Taewa and ben-kaufman August 25, 2026 17:30

Navigation Menu

Uh oh!

Feat/paykit payment lock demo - #10

Feat/paykit payment lock demo#10
dzdidi wants to merge 12 commits into
masterfrom
feat/paykit-payment-lock-demo

dzdidi commented Aug 4, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

dzdidi commented Aug 25, 2026 •

edited

Loading

Uh oh!

dzdidi commented Aug 25, 2026 •

edited

Loading

Uh oh!

dzdidi commented Aug 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

dzdidi commented Aug 4, 2026

Summary

Contract and risk impact

Verification

Documentation

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

dzdidi commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dzdidi commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dzdidi commented Aug 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dzdidi commented Aug 25, 2026 •

edited

Loading

dzdidi commented Aug 25, 2026 •

edited

Loading