feat(ci): provision native client generators and validate NPM candidates

[PastaPastaPasta]

Platform's NPM release build currently runs protoc through the host Docker daemon. A runner inside a container cannot reliably bind-mount its checkout this way, and the new unprivileged runner image deliberately has no Docker CLI or socket.

This adds a native client-generation toolchain under /opt/client-codegen, separate from Rust's protoc 32.0. It builds checksum-pinned protobuf 3.18.1, gRPC 1.46.3 Objective-C/Python plugins and gRPC Java 1.42.1, preserving the existing generator versions. Platform supplies its Yarn-locked TypeScript plugin. Companion: dashpay/platform#5068. The standalone builder also supports unprivileged local development on Linux and macOS.

The optional client_codegen image requirement binds those sources to the reviewed recipe. Candidate routing accepts NPM validation jobs without devices or Docker authority; promotion requires successful Rust, Kotlin and NPM jobs on the same full PR head/image digest. Older manifests retain their existing Rust/Kotlin contract.

Validation:

• Built the native compilers on macOS ARM64 and Ubuntu 24.04 AMD64.
• Compared Platform's complete generated client tree with rvolosatovs/protoc:4.0.0@sha256:92c69fafae44d73c6446c8a0fdc6fa8fd8336ad7926bbc1d08ce651d864bdcaf: byte-identical.
• Built the full runner image locally; its native compiler checks and confined smoke test passed as UID 1001, with no network, capabilities, sudo or Docker socket. The final pinned revision also passed Platform DAPI generation, 32 unit tests, three generation regressions and packing checks inside the full image, with networking disabled and no Docker socket.
• 22 contract/lifecycle tests pass; lock/template validation, Python compilation, workflow lint and diff checks pass.
• Linux CI passed the full image build, confined smoke tests, actual Android emulator/KVM boot, OCI export and separate-machine import.

Rollout remains gated on the companion Platform changes and the bootstrap/Rust/Kotlin routing in dashpay/platform#4912 and dashpay/platform#4702. The trusted bootstrap's reusable-workflow and control_revision pins, and the operator controller checkout, must all move to a reviewed revision supporting client_codegen/npm. Image publication alone does not update live runners. Register dedicated npm-build release capacity only after the complete release build/pack validation succeeds. The Platform companion requires the platform-npm-releases group restricted to its protected reusable release workflow, with HOME, workspaces and Cargo caches separate from npm-pr validation capacity; see its NPM runner runbook.

This pull request was created by Codex.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Warning

Review limit reached

Next included review available in 33 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 60e1d8cd-1b3f-422b-b10b-92abd2a55eab

📥 Commits

Reviewing files that changed from the base of the PR and between e49e8bc and bb1246d.

📒 Files selected for processing (1)

• README.md

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: da92ad23-6246-4222-a48d-75f68fc26ee6

📥 Commits

Reviewing files that changed from the base of the PR and between ac9ef5b and e49e8bc.

📒 Files selected for processing (16)

• .dockerignore
• Dockerfile
• Dockerfile.template
• README.md
• client-codegen/CMakeLists.txt
• client-codegen/build.py
• client-codegen/lock.json
• client-codegen/smoke.py
• docs/platform-pr-images.md
• image.lock.json
• scripts/candidate_runner.py
• scripts/image_contract.py
• scripts/platform_request.py
• scripts/verify-image.py
• tests/test_image_contract.py
• tests/test_platform_lifecycle.py

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The pull request adds an optional native client-codegen toolchain with pinned sources, image build and verification support, and an NPM candidate validation requirement for manifests that include client_codegen.

Changes

Client codegen integration

Layer / File(s)	Summary
Build and smoke-test the locked toolchain client-codegen/CMakeLists.txt, client-codegen/build.py, client-codegen/lock.json, client-codegen/smoke.py	Adds pinned source archives and CMake build targets. The build script verifies archive checksums and the installed protoc version. The smoke script checks generated client files.
Image build and codegen verification .dockerignore, Dockerfile, Dockerfile.template, image.lock.json, scripts/image_contract.py, scripts/verify-image.py, tests/test_image_contract.py	Adds the recipe and lock data to image builds. The image contract validates the optional lock entry, and image verification checks the codegen lock and runs the smoke script when configured.
Conditional NPM candidate proof scripts/candidate_runner.py, scripts/platform_request.py, tests/test_platform_lifecycle.py, README.md, docs/platform-pr-images.md	Adds NPM candidate discovery and requires successful NPM release-build validation on the same digest when client_codegen is required. Tests and documentation cover the conditional requirement and candidate permissions.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant BuildScript as client-codegen/build.py
  participant LockFile as client-codegen/lock.json
  participant Archives as Locked source archives
  participant CMake
  participant Stage as Staged installation
  BuildScript->>LockFile: Read versions, URLs, and checksums
  BuildScript->>Archives: Download source archives
  BuildScript->>BuildScript: Verify SHA-256 checksums
  BuildScript->>CMake: Configure and build targets
  CMake->>Stage: Install binaries and build outputs
  BuildScript->>Stage: Check protoc version before publication

Loading

Suggested reviewers: infraclaw-dash

Merge Risk: ⚪ Minimal · up to e49e8

No concrete issue remains that should block merging after normal checks.

Security Architecture Review

Security architecture risk: 🟡 Moderate · up to e49e8

The new generator build and NPM validation gate have meaningful security boundaries. Checksums, restricted candidate runners, and digest-bound promotion limit exposure, but the companion workflows and enforcement of the documented build isolation could not be verified here.

Retained concerns

• Medium · security · inferred: The new image build compiles checksum-pinned third-party source, including its CMake build logic, during the root build stage. Checksums fix the selected bytes but do not contain their build-time behavior; the effective boundary depends on the documented isolated builder and control over recipe revisions, whose enforcement was not available to verify.

Security review details

Security Blast Radius

• inferred — The newly executable downloaded-source boundary is in image construction. The intended containment is a disposable, credential-limited builder; the supplied source does not establish the deployed workflow's enforcement of that containment.

Trust Boundaries and Controls

• observed — The NPM candidate path inherits PR-head, digest, trusted-publisher and runner-group checks. Promotion requires an NPM success from its named workflow when client_codegen is requested; the controller itself does not check that requirement before admitting an NPM-labeled queued job.

Resilience and Maintainability Implications

• observed — Candidate reconciliation records registrations before starting containers, removes completed or expired managed containers, waits on busy registrations, and stops automatic retries after three failed attempts.

Hardening Proposals

• proposed — Verify in the companion workflows that only an authorized, revision-pinned recipe reaches the isolated builder and that NPM candidate labels are issued under the intended manifest and fork-approval conditions. Those workflow policies are not established by the files available here.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 8 files. (8 skipped: 8…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes both primary changes: provisioning native client generators and validating NPM candidates.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 8 files. (8 skipped: 8 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}