shorebird/OPEN_SOURCE_REPLACEMENTS.md

Open Replacement Audit

Last verified: 2026-06-25.

This workspace is intended to build and operate without closed Shorebird services or closed SDK artifacts. Local forks/submodules are the source of truth: do not clone official Shorebird infrastructure repositories as a bootstrap default.

Local Sources

The combined workspace provides these open replacements:

Surface	Open replacement in this workspace
Shorebird CLI	packages/shorebird_cli, configured for the self-hosted server and open artifact mirror
CodePush client/protocol	packages/shorebird_code_push_client and packages/shorebird_code_push_protocol
CodePush API/auth/console	../shorebird-server
Artifact mirror/proxy	packages/artifact_proxy
Runtime updater library	../updater/library, linked into the Flutter engine by ../scripts/sync_open_sources.sh
Patch artifact generator	../updater/patch and packages/open_aot_patch_tools
Flutter engine and Flutter tool defaults	../flutter, linked to ../dart-sdk and ../updater
Dart VM patch runtime	../dart-sdk

Run source linking from the workspace root:

./scripts/sync_open_sources.sh

The script links:

flutter/engine/src/flutter/third_party/dart -> dart-sdk
flutter/engine/src/flutter/third_party/updater -> updater

Set UPDATER_SRC explicitly only when testing another updater fork. The default path must remain the local updater submodule.

Hosted Surfaces

The open CLI, CodePush client, updater, artifact proxy, and Flutter tool defaults are configured to use local/self-hosted origins when no override is supplied:

Hosted surface	Open default
API/auth server	http://localhost:8080
OpenAPI contract	http://localhost:8080/openapi.yaml and ../shorebird-server/internal/api/handlers/openapi.yaml
CLI patch-tool artifact mirror	http://localhost:8080/artifacts
Flutter engine/Dart SDK/Maven artifact mirror	http://localhost:8080/download.flutter.io
Web console	self-hosted shorebird-server/web dashboard

Override these values with SHOREBIRD_HOSTED_URL, SHOREBIRD_ARTIFACT_BASE_URL, SHOREBIRD_FLUTTER_STORAGE_BASE_URL, and SHOREBIRD_FLUTTER_GIT_URL when pointing the CLI at a public mirror. Full SDK CI runs upload open-shorebird-artifact-mirror, which is assembled from the produced patch-tool, metadata, engine, and web artifacts. They also upload open-shorebird-release-manifest, which validates checksum sidecars and records provenance for the CLI, server, SDK, engine, and mirror archives. After downloading CI artifacts manually, run the root scripts/assemble_artifact_mirror.sh helper to reproduce that merge, validate artifacts_manifest.yaml, verify platform patch-*.zip tools, and write missing checksum sidecars before publishing the directory behind SHOREBIRD_ARTIFACT_BASE_URL.

Platform Patch Routes

Platform	Patch route
iOS	Encrypted Dart bytecode interpreter artifact with DART_DYNAMIC_MODULES=false; does not load downloaded native executable text
Android	Native AOT patch runtime using the public updater patch binary and a patch-capable Android engine
macOS/Linux	Native AOT patch runtime using the public updater patch binary and patch-capable desktop engines
Windows	Public updater patch binary; runtime verification remains platform-runner dependent
Web	SDK artifact build only; not a Shorebird CodePush release platform in this CLI/protocol

The iOS App Store candidate route is interpreter-based. Do not reintroduce DART_DYNAMIC_MODULES, aot-tools.dill publishing, or a native-AOT iOS patch route as the default.

CI Contract

The root workflow .github/workflows/open-shorebird-ci.yml builds:

• CLI archives containing shorebird, open_aot_patch_tools, and artifact_proxy
• public updater patch-*.zip mirror artifacts
• self-hosted shorebird-server binaries
• custom Dart SDK artifacts
• Linux, Android, web, iOS, and macOS engine/SDK artifacts on manual full_sdk_build=true runs

../scripts/verify_ci_workflow.sh is the executable contract for this audit. It rejects closed hosted defaults, DART_DYNAMIC_MODULES=true, legacy aot-tools.dill publishing, missing checksum sidecars, missing source tests, and missing required artifact jobs.

Security Boundary

The open updater, local server, CLI, and patch tools must enforce:

• patch metadata compatibility: app id, release/build id, platform, arch, SDK hash, base snapshot hash, flavor id, and license type
• cryptographic integrity through hash pinning/signing where supported
• AES-GCM delivery confidentiality and tamper detection for encrypted interpreter payloads
• limited offline-license expiry through offline_expires_at

Open replacement work should preserve Shorebird-compatible protocol shapes where the CLI/updater expect them, while keeping service origins, SDK builds, and patch tools controlled by this workspace.