DanS
a78a13edf3
- docs/lite-wallet-implementation-plan-v2-2026-06-04.md: vertical-slice plan that supersedes the v1 plan (now banner-marked); carries over the inherited artifact/ signing/phase-2 design docs for reference. - scripts/check-source-hygiene.sh: pre-commit/CI guard rejecting >80-char filenames and chained churn-token names, to stop the deleted "_plan"/"_batch" scaffolding from regrowing. - CLAUDE.md: repository guidance for future sessions. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
106 lines
8.4 KiB
Markdown
106 lines
8.4 KiB
Markdown
# Lite Wallet Backend Source And Signature Metadata Plan - 2026-05-20
|
|
|
|
## Purpose
|
|
|
|
This Phase 1 note closes the planning gap between the verified portable dependency override and the eventual release-source layout. It also defines the signature metadata boundary for backend artifacts without enabling signing, upload, publication, runtime loading, SDXL calls, or wallet mutation.
|
|
|
|
## Current Source State
|
|
|
|
The checked-in backend wrapper is `external/SilentDragonXLite/lib`. Its Cargo package is `qtlib`, the library name is `silentdragonxlite`, and the crate type is `staticlib`.
|
|
|
|
The wrapper now depends on `silentdragonxlitelib` through the reviewed relative path:
|
|
|
|
```toml
|
|
silentdragonxlitelib = { path = "../silentdragonxlite-cli/lib" }
|
|
```
|
|
|
|
The maintained dependency branch was imported from `/home/d/external/silentdragonxlite-cli` into `external/SilentDragonXLite/silentdragonxlite-cli` from git revision `6a178c8d08d9c1c153fb22759a68177cdb787be7`. Build outputs, `.git`, and `target/` were not imported, and stale workflow conflict-backup files were pruned from the vendored copy. The imported source carries `DRAGONX_SOURCE_REVISION` so artifact manifests can keep reporting the maintained dependency revision even though the dependency is now vendored under the wrapper source tree.
|
|
|
|
The release-builder-safe path is now to build from `external/SilentDragonXLite/lib` without `--silentdragonxlitelib-dir`. The override remains available as an escape hatch for comparing against an external maintained checkout, but release builders should prefer the checked-in relative layout.
|
|
|
|
## Implemented Relative Layout
|
|
|
|
The reviewed backend source branch should make the dependency relative inside a single release source tree. The preferred layout is:
|
|
|
|
```text
|
|
external/SilentDragonXLite/
|
|
lib/ # qtlib C ABI wrapper, crate type staticlib
|
|
silentdragonxlite-cli/
|
|
Cargo.toml # dependency workspace root
|
|
lib/ # package silentdragonxlitelib
|
|
```
|
|
|
|
With that layout, `external/SilentDragonXLite/lib/Cargo.toml` uses:
|
|
|
|
```toml
|
|
silentdragonxlitelib = { path = "../silentdragonxlite-cli/lib" }
|
|
```
|
|
|
|
Acceptable variants are allowed only if they keep both crates inside the reviewed release source tree and use a relative path. Absolute builder-local paths, symlinks to paths outside the tree, generated source patches committed back into the repo, or reliance on `/home/d/external` are not release-acceptable.
|
|
|
|
## Implementation Status
|
|
|
|
Completed through 2026-05-22:
|
|
|
|
1. Imported the maintained `silentdragonxlite-cli` source into the reviewed backend source tree.
|
|
2. Changed the wrapper dependency path from the absolute local path to `../silentdragonxlite-cli/lib`.
|
|
3. Left `external/SilentDragonXLite/lib/Cargo.lock` unchanged.
|
|
4. Updated artifact provenance so the script discovers relative `silentdragonxlitelib` sources, remaps them for reproducible builds, and records `portable_dependency_override: false` unless `--silentdragonxlitelib-dir` is explicitly used.
|
|
5. Built a Linux artifact without `--silentdragonxlitelib-dir` from `external/SilentDragonXLite/lib`.
|
|
6. Built two Windows GNU artifacts without `--silentdragonxlitelib-dir`, compared them byte-for-byte, and linked the app target against the relative-source artifact.
|
|
7. Rechecked macOS from the relative source layout on 2026-05-22; this Linux host still lacks Apple Rust targets and Apple/osxcross linker tooling, so the `x86_64-apple-darwin` attempt failed before artifact production.
|
|
8. Defined the Phase 1 signing policy in `docs/lite-wallet-backend-signing-policy-2026-05-22.md`, added read-only signature metadata capture to `scripts/build-lite-backend-artifact.sh`, added optional `DRAGONX_LITE_BACKEND_REQUIRE_SIGNATURE` CMake enforcement, and taught `LiteBackendArtifactContract` to validate required signature metadata before producing resolver input.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- `external/SilentDragonXLite/lib/Cargo.toml` contains no absolute `silentdragonxlitelib` dependency path.
|
|
- The dependency source is present inside the reviewed source tree and is covered by source-control revision/provenance review.
|
|
- `scripts/build-lite-backend-artifact.sh --platform linux --backend-dir external/SilentDragonXLite/lib --reproducible ...` succeeds without `--silentdragonxlitelib-dir`.
|
|
- The generated manifest records `portable_dependency_override: false`, `cargo_build_source` equal to the reviewed backend source, and reproducible provenance.
|
|
- The refreshed Linux no-override artifact is `build/lite-backend-relative-linux-b/linux/libsilentdragonxlite.a` with SHA-256 `8fd6c66ff661e13f768754de69d39e1a15ee55b6fdd530625a6018c867edde10`; its manifest records `portable_dependency_override: false`, `silentdragonxlitelib_revision: 6a178c8d08d9c1c153fb22759a68177cdb787be7`, `reproducible: true`, and `signing_requested: false`.
|
|
- The refreshed Windows GNU no-override artifacts are byte-identical at SHA-256 `ca7677af58f61de4bd56311e76e32961d977da8fac2a3c5d158c1702f8807439`; their manifests record `portable_dependency_override: false`, `silentdragonxlitelib_revision: 6a178c8d08d9c1c153fb22759a68177cdb787be7`, `reproducible: true`, `rust_target: x86_64-pc-windows-gnu`, and `signing_requested: false`.
|
|
- The relative Windows GNU artifact links into `ObsidianDragon` from `/tmp/od-win-relative-link` with `DRAGONX_LITE_BACKEND_EXTRA_LIBS=secur32;userenv`, producing `/tmp/od-win-relative-link/bin/ObsidianDragonLite.exe` as a PE32+ GUI x86-64 Windows executable. The import table includes `Secur32.dll` and `USERENV.dll`; the executable was inspected but not run.
|
|
- macOS uses the same relative layout once a macOS/osxcross builder exists; the 2026-05-22 Linux preflight failed with missing `x86_64-apple-darwin` standard libraries and produced no artifact or manifest, and macOS verification is deferred for now by operator request.
|
|
- All artifacts still expose the eight required `litelib_*` symbols for ABI `sdxl-c-v1`.
|
|
|
|
## Signature Metadata Boundary
|
|
|
|
Phase 1 backend artifact production records signature verification metadata under policy `dragonx-lite-backend-signature-policy-v1`, defined in `docs/lite-wallet-backend-signing-policy-2026-05-22.md`. It must not create signatures, mutate artifacts, upload artifacts, publish artifacts, or make signatures a runtime wallet concern.
|
|
|
|
When policy exists, the artifact manifest should add a read-only metadata object with these fields or direct equivalents:
|
|
|
|
```json
|
|
{
|
|
"signature_verification": {
|
|
"policy_defined": true,
|
|
"required_for_release": true,
|
|
"verification_performed": true,
|
|
"verification_status": "verified",
|
|
"signature_format": "minisign|gpg|sigstore|external|other",
|
|
"signature_path": "/path/to/artifact.signature",
|
|
"signature_file_sha256": "sha256 of sidecar signature file",
|
|
"verification_tool": "tool name and version",
|
|
"verification_command": "command already run by release builder when recorded",
|
|
"key_fingerprint": "reviewed public key fingerprint when applicable",
|
|
"certificate_identity": "certificate identity when applicable",
|
|
"certificate_issuer": "certificate issuer when applicable",
|
|
"transparency_log_url": "transparency log entry when applicable",
|
|
"verified_artifact_sha256": "sha256 that was verified"
|
|
}
|
|
}
|
|
```
|
|
|
|
Unsigned local manifests keep `signing_requested: false`, `metadata_provided: false`, and `verification_status: "not-provided"`. Signed release-builder manifests may set `metadata_provided: true` only when the sidecar signature exists, verifier metadata is recorded, a reviewed trust identity is present, and `verified_artifact_sha256` matches the artifact SHA-256.
|
|
|
|
## Signature Metadata Acceptance Criteria
|
|
|
|
- Signature metadata is read-only inventory attached to the artifact manifest.
|
|
- The metadata verifies the same artifact bytes identified by the manifest SHA-256.
|
|
- If `--signature-required` or `DRAGONX_LITE_BACKEND_REQUIRE_SIGNATURE=ON` is used, missing or invalid signature metadata fails before CMake imported-link use.
|
|
- Signature verification tooling and public-key or certificate trust roots are documented outside wallet runtime code.
|
|
- `LiteBackendArtifactContract` and runtime bridge code continue to reject signing requests and never sign, upload, publish, or mutate artifacts.
|
|
|
|
## Remaining Phase 1 Work
|
|
|
|
- Capture real signed-artifact evidence when a release builder provides sidecar signatures and reviewed trust roots.
|
|
- macOS artifact and imported-link verification is deferred by operator request until a macOS host or configured osxcross builder is available and the deferral is lifted. |