# 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.