feat: package OpenShell for Fedora

Start with the root-level openshell.spec and the listed child issues, especially #1969, #2204, and #3454; inspect the current source, vendor inputs, and Fedora build constraints. Done means the package builds from source with rpmbuild/mock without network access after %prep, has documented dependency and license handling, and passes Fedora Rawhide and package-review requirements.

User Story

As a Red Hat engineer helping productize OpenShell for internal RPM/entitlement use, and as an OpenShell contributor, I want OpenShell available as a properly reviewed Fedora package, so Fedora users and downstream consumers can install it through their normal package manager instead of install scripts or third-party COPR repos.

Problem Statement

OpenShell has no path into Fedora today. The repo carries a root-level openshell.spec intended for Fedora/EPEL, and a .packit.yaml that already automates source/vendor tarball generation and version injection — but the spec itself isn't build-ready as checked in: %build consumes externally prebuilt binaries rather than compiling from source, which Koji/mock cannot support. Getting into Fedora also requires resolving vendored-dependency policy questions (~600 vendored Rust crates), a bundled library with a system equivalent (Z3), a vendored crypto stack that bypasses system crypto policy, and a Python SDK subpackage whose build-time proto tooling may not be compatible with what Fedora ships.

Impact / Why This Matters

Several Red Hat product efforts want a supported, source-buildable path to OpenShell RPMs; Fedora-first is one of two distribution paths being evaluated internally, and landing in Fedora is more durable and community-aligned than an internal-only channel. Today the only RPM path is a hand-rolled internal COPR build — not Fedora-reviewed, not broadly redistributable.

Proposed Design

Work through the concrete engineering items below roughly in the order listed, then proceed through Fedora's package review process once the spec is review-ready.

Open architecture question raised by @andrelustosa: maintain the current root openshell.spec (prebuilt-binary, fast for developer iteration) and a separate Fedora-targeted spec (fully source-building, vendored) rather than converting the single existing spec in place. Versions would stay in sync between the two. This is a reasonable option — the two-spec split is mechanical (vendored-vs-prebuilt %build), not divergent logic — but it means deciding which spec .packit.yaml's specfile_path should point to, and either fixing openshell.spec in place or introducing a second file. Needs a decision before item 1 below is scoped for real.

Acceptance Criteria

• openshell.spec (or its Fedora-targeted counterpart, per the two-spec decision above) builds via rpmbuild/mock from source with no network access after %prep
• Vendored dependencies, plus non-crate content (docs, man pages, systemd unit, Python SDK files), are license-audited and correctly reflected in License:
• Z3 and vendored-crypto bundling concerns are resolved or explicitly documented
• A package review request is filed and approved via Fedora's New Package Process
• OpenShell builds successfully in Fedora Rawhide

Alternatives Considered

• Internal-only RPM distribution (via an internal COPR/entitlement channel) — already in progress in parallel by a separate internal team; faster to a shippable artifact but doesn't benefit the broader Fedora/community ecosystem and adds a second packaging surface to maintain long-term.
• Container-image-only distribution (status quo) — doesn't meet the needs of consumers who want a system-package-manager-installable binary.

---

Work Items

1. Fix %build to compile from source instead of consuming prebuilt binaries

User Story: As someone building OpenShell via rpmbuild/mock (Fedora's build path), I want %build to actually invoke cargo build, so the package can build in a network-isolated Fedora build environment.

Problem: %build only runs test -x "${OPENSHELL_PREBUILT_BINARIES_DIR}/openshell" (and equivalents for gateway/prover); %install copies binaries from that externally populated directory. No compilation happens inside the RPM build. Scope here depends on the two-spec decision above — this may mean fixing openshell.spec in place, or building a new Fedora-targeted spec from scratch using this as the reference for what's wrong.

Impact: Disqualifying for Fedora — Koji requires building from source inside its sandboxed, network-isolated root. The current external-CI workaround has no Fedora equivalent.

Acceptance Criteria:

• %build runs cargo build --release --offline --locked for openshell, openshell-gateway, openshell-prover against the %cargo_prep-vendored sources
• Builds successfully in a mock chroot with networking disabled
• No remaining dependency on OPENSHELL_PREBUILT_BINARIES_DIR or similar
• %global debug_package %{nil} is either resolved (debuginfo generated properly) or explicitly justified — this is a known Fedora review flag and reviewers will ask about it directly

2. Generate Python protobuf stubs during the build — and confirm Fedora's grpcio-tools can actually build them

User Story: As a Fedora packager building python3-openshell, I want the protobuf stubs generated as part of the build, so the package doesn't ship stale or missing files, and I want confidence that Fedora's own tooling can actually produce a working SDK.

Problem: python/openshell/_proto/*.py is .gitignored, produced by tasks/scripts/generate_python_proto.py. %install copies these files but nothing in %prep/%build generates them first. Separately, openshell.spec already carries a comment acknowledging Fedora ships older grpcio/protobuf than the SDK needs (grpcio 1.48 / protobuf 3.19 vs. the SDK's >=1.60 / >=4.25 requirement), currently worked around by using Recommends instead of Requires for the runtime dependency. That workaround doesn't address whether Fedora's python3-grpcio-tools can even generate correct stubs at build time.

Impact: Without proto generation in the build, the subpackage either fails to build cleanly from a clean checkout or silently packages stale stubs. Separately, if Fedora's grpcio-tools/protobuf versions are genuinely incompatible with what the generated stubs need at runtime, shipping python3-openshell via Fedora's system packages may not work at all regardless of how proto-gen is wired up.

Open question raised by @andrelustosa, unresolved: either (a) drop the python3-openshell subpackage from the Fedora package entirely, or (b) vendor python3-grpcio-tools and python3-protobuf alongside the Rust dependency tree. Needs someone to actually test proto generation and the resulting SDK against Fedora's shipped grpcio/protobuf versions before choosing.

Acceptance Criteria:

• %prep/%build runs proto generation offline against vendored proto/*.proto, if the subpackage is kept
• Fedora's python3-grpcio-tools/python3-protobuf versions are tested against the SDK's actual requirements; decision made to drop the subpackage or vendor its Python build/runtime deps
• Builds successfully from a clean checkout
• %check verifies stub files exist and import correctly (if kept)

3. Harden and verify the existing .packit.yaml source/vendor generation — not a new script

User Story: As a packager maintaining openshell.spec across version bumps, I want confidence that source and vendor tarball generation is reproducible and correct, so every release can be re-packaged consistently and reviewed.

Correction: this is not greenfield work — .packit.yaml's create-archive action already does both halves: it builds openshell-${VERSION}.tar.gz via git ls-files+tar, and openshell-${VERSION}-vendor.tar.xz via cargo vendor --locked. Flagged by @andrelustosa and confirmed by inspecting the file directly. The work here is verifying and hardening this existing mechanism, not writing a new script.

Impact: Fedora review requires packagers to explain and reproduce exactly how sources were generated — a standard reviewer question. The existing Packit actions answer that, but need to be verified as actually correct and actively exercised (see item 8 — evidence that these are running at all is currently missing).

Acceptance Criteria:

• Confirm create-archive's output matches what openshell.spec's Source0/Source1 expect, including the item-2 proto-stub question
• Confirm fix-spec-file's version/release injection (see item 4) is compatible with whatever %build fix lands in item 1
• Document the existing mechanism in the spec's header comment so it's not mistaken for missing again

4. Verify the version/Release scheme — largely already handled by .packit.yaml

User Story: As a Fedora packager, I want Version/Release to follow Fedora's guidelines, so the package can be tracked through normal Fedora update tooling.

Correction: the checked-in spec's stale %global openshell_version 0.0.37 and unusual git-describe-style Release are very likely just placeholders — .packit.yaml's fix-spec-file action already rewrites both %global openshell_version and Release (via OPENSHELL_RPM_RELEASE/PACKIT_RPMSPEC_RELEASE) as part of CI-driven builds. This needs verifying rather than assuming the checked-in values are the real bug.

Impact: If fix-spec-file is working correctly, this item is mostly about documentation and confirming the mechanism — not building new version-bump tooling. If it's not actually wired into a real build path (see item 8), this is still an open problem.

Acceptance Criteria:

• Confirm fix-spec-file actually produces a Fedora-conformant Version/Release in a real build
• Document the actual source of truth for Version/Release (Packit-injected vs. hand-maintained) so packagers don't get confused by the checked-in placeholder values
• If fix-spec-file isn't sufficient or isn't active, fall back to a manual %autorelease/%autochangelog approach

5. Aggregate all licenses — vendored crates and non-crate content — into an accurate SPDX License: tag

User Story: As a packager and downstream RPM consumer, I want License: to accurately reflect every license shipped in the binary, so the package is legally accurate and passes Fedora licensing review.

Problem: openshell.spec sets License: Apache-2.0, but the binaries statically bundle ~600 vendored crates under mixed licenses (MIT, BSD variants, MPL-2.0, Unicode-3.0, ISC, etc.). %cargo_license/cargo_license_summary generate a report for crates, but nothing reconciles it into the spec's License: field. Separately (raised by @andrelustosa): non-crate content — man pages, the systemd unit, docs, and the Python SDK's own source files — also needs explicit license accounting; the crate-license tooling doesn't cover any of it.

Impact: Fedora requires License: to be an SPDX expression covering every shipped license, not just the project's own. An inaccurate tag is a hard review blocker, and any license not on Fedora's allowed list needs a Fedora Legal conversation.

Proposed Design: Compute the aggregated SPDX expression from %cargo_license's output as part of item 3's tooling for the crate side; manually audit and document licenses for non-crate content separately, since there's no automated tooling for that half.

Acceptance Criteria:

• License: (per subpackage as needed) is a correct SPDX union of all shipped licenses, crate and non-crate
• Any non-allowed license is flagged for Fedora Legal review
• A repeatable process re-checks crate-license aggregation whenever Cargo.lock changes
• Non-crate content licenses are documented explicitly, not assumed to inherit the project's Apache-2.0

Alternatives Considered: One-time manual audit/hand-patch — rejected; will drift silently as dependencies change. Leave as Apache-2.0 — rejected; this is a licensing-accuracy problem independent of Fedora.

6. Resolve Z3 bundling — build against system z3-devel

Already tracked separately — see #1969 ("unbundle Z3 from gateway runtime packaging"). z3-src-* is currently vendored whole for the gateway's bundled-z3 feature; Fedora already ships z3 as a system package, and the Bundled Libraries policy expects linking against it where upstream supports that.

Corroborated as tractable, not just theoretical: both @andrelustosa's own RHEL spec and Red Hat's internal Hummingbird downstream spec (rpms/openshell/openshell.spec in redhat/hummingbird/rpms) already build against BuildRequires: z3-devel successfully instead of vendoring z3-src. This is a proven pattern, not a hypothetical — resolving #1969 should be able to copy this approach directly.

Not duplicating #1969 here; resolving it is a prerequisite for this effort.

7. Document the vendored-crypto (aws-lc-rs/rustls/ring) bundling justification

User Story: As a Fedora reviewer or security-conscious consumer, I want a documented justification for why OpenShell bundles its own TLS/crypto stack instead of system OpenSSL, so the decision is auditable.

Problem: The vendor tree includes aws-lc-rs, aws-lc-sys, ring, rustls (plus tokio-rustls, quinn) — a fully vendored crypto/TLS stack that bypasses update-crypto-policies. This is a known Fedora Rust-review flashpoint and is independently flagged internally as a FIPS blocker for a separate internal RPM effort.

Impact: Without a documented justification, this will likely draw direct reviewer pushback, and it's a shared blocker with the internal RHOAI/RHAIE effort — resolving it once here benefits both.

Confirmed sufficient as scoped by @andrelustosa: FIPS compliance is the real underlying problem, but documenting it as a known, flagged gap (rather than attempting a fix in this effort) is an acceptable answer for now.

Proposed Design: Investigate whether an OpenSSL-backed feature flag is feasible without a large refactor; if not, write the formal bundling-exception rationale for Fedora review.

Acceptance Criteria:

• Written justification (spec comments and/or packaging doc) covering why the stack is vendored, whether that's expected to change, and current blockers
• Explicit coordination noted with the related internal FIPS/crypto-policy effort

Alternatives Considered: Switch to OpenSSL-backed TLS now — likely correct long-term but too large for this push; tracked as a documented gap instead. Say nothing, let a reviewer raise it — rejected; better to get ahead of a known blocker.

8. Verify whether .packit.yaml's existing copr_build jobs are actually active — then build/validate the spec

User Story: As a maintainer of openshell.spec, I want CI to actually build the package, so future changes don't silently break Fedora buildability again.

Correction: .packit.yaml already defines copr_build jobs targeting fedora-all and epel-10 on pull_request, commit, and release triggers — exactly this item's ask, at least on paper. Flagged by @andrelustosa. However, this could not be confirmed as actually active: checking several recent PRs (including CI-focused ones) turned up zero Packit/Copr status checks of any kind. This suggests the Packit GitHub App may not be installed/enabled for this repo, or the jobs aren't reporting back — not that the config is wrong, but that it's unverified whether it runs at all today.

Impact: If genuinely active, this item may already be substantially solved and just needs confirmation + hardening. If not active, this is still fully open, and tasks/scripts/test-packaging-assets.sh's string-only assertions remain the only current check — which never invokes rpmbuild/mock.

Acceptance Criteria:

• Confirm with a maintainer/Andre/Robby whether the Packit GitHub App is actually installed and these copr_build jobs are live
• If active: verify they actually catch a real %build breakage (e.g. temporarily reintroduce a known failure and confirm the check fails)
• If not active: get it activated, or fall back to a mock-based GitHub Actions job as originally proposed
• Coordinated with #3454 rather than duplicating it

Alternatives Considered: Periodic manual builds — rejected; exactly the kind of check that rots without automation. Only catch breaks via Rawhide/COPR post-merge — rejected as too late.

---

Related: #1969, #2204, #3454. Duplicates #3509 and #3511 (both closed) — this issue (#3510) is the canonical one going forward.

Checklist

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request