ObsidianDragon/docs/lite-wallet-backend-source-signature-plan-2026-05-20.md

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:

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:

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:

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:

{
  "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.