Fenris/docs/spec/xbps-proof-results.md

XBPS Proof of Concept Results (Issue #83)

Status: Complete. All acceptance criteria satisfied.

Summary

Signed XBPS installation and immediate updates through Gitea have been demonstrated and verified end-to-end. The publication mechanism is repeatable and documented for subsequent tickets.

Acceptance Criteria Results

1. Permanent raw URL delivery without LFS indirection

Result: PASS

All artifacts are served directly by Gitea via raw-file URLs:

• Repository: https://git.bongbetic.com/xavierk/Fenris-xbps
• Raw URL pattern: https://git.bongbetic.com/xavierk/Fenris-xbps/raw/branch/stable/x86_64/<file>

Verified files:

• x86_64-repodata (1327 bytes) — HTTP 200
• fenris-0.3.5_1.x86_64.xbps (731 bytes) — HTTP 200
• fenris-0.3.5_1.x86_64.xbps.sig2 (384 bytes) — HTTP 200
• fenris-0.3.6_1.x86_64.xbps (752 bytes) — HTTP 200
• fenris-0.3.6_1.x86_64.xbps.sig2 (384 bytes) — HTTP 200

No LFS indirection detected. Files served as ordinary Git blobs.

2. Signing-key handling and trust verification

Result: PASS

Signing uses SSH RSA keys (3072-bit) via xbps-rindex --sign-pkg and xbps-rindex --sign. The public key is embedded in the repository metadata (index-meta.plist) within the repodata archive. XBPS clients prompt for key import on first access and verify signatures automatically.

Key characteristics:

• Private key: SSH RSA format, stored externally (not in repository)
• Public key: Embedded in repodata, base64-encoded PKCS#8 format
• Package signatures: .sig2 files alongside each .xbps archive
• Repository signature: Embedded in x86_64-repodata metadata

3. Install and update with client that fetched old index

Result: PASS

Demonstrated full lifecycle:

1. Fresh install of v0.3.5 from repository with only v0.3.5 in index
2. Added v0.3.6 to index and committed to stable branch
3. Client performed xbps-install -Syu and upgraded from 0.3.5 → 0.3.6

The upgrade was detected and executed without manual intervention:

fenris (0.3.5_1 -> 0.3.6_1)

4. Cache behavior and binary size limits

Result: PASS (with documented caveat)

Cache behavior:

• Gitea raw endpoint: cache-control: public, max-age=21600 (6-hour cache)
• ETag changes on each commit (different file hash)
• Conditional requests with old ETag return 200 (full content), not 304

xbps-install behavior:

• Always fetches fresh repodata with -S flag
• Respects ETag changes for immediate discovery
• No 6-hour delay observed in practice

Binary size limits:

• Test packages: 731–752 bytes (small test artifacts)
• Real packages expected to be <10MB (vendored pure-Python)
• Gitea serves any file size without LFS

Caveat: Clients using xbps-install -Su without -S may use cached repodata. The -S flag forces a fresh fetch. Users should always use -Syu for updates.

5. Publish index/artifacts together, preserve older artifacts, safe failure recovery

Result: PASS

Publication mechanism:

• Index and new package committed together in single Git commit
• Older package artifacts retained in tree (e.g., v0.3.5 alongside v0.3.6)
• Clients with cached older indexes can still download older packages

Failure recovery:

• Demonstrated with simulated corruption (corrupted repodata committed)
• Recovery via git revert restored correct state
• Previous state accessible via Git history at all times

6. Record results and publication mechanism

Result: PASS

Publication script created: scripts/xbps-publish.sh

• Automates: build → sign → clone repo → update index → commit → push
• Supports --dry-run and --publish modes
• Follows same pattern as existing scripts/release.sh

Makefile targets added:

• package-xbps — Build XBPS package
• sign-xbps — Sign XBPS package
• xbps-publish — Publish to distribution repository
• xbps-publish-dry-run — Dry-run publication

Repository Structure

xavierk/Fenris-xbps (stable branch)
  x86_64/
    fenris-<version>_1.x86_64.xbps       # Package archives
    fenris-<version>_1.x86_64.xbps.sig2   # Package signatures
    x86_64-repodata                        # Repository index (zstd-compressed tar)
    x86_64-repodata.sig2                   # Repository metadata signature
  keys/
    fenris-xbps-signing.pub                # Public signing key
  README.md

Client Configuration

Users add the repository to /etc/xbps.d/xbps.conf:

repository=https://git.bongbetic.com/xavierk/Fenris-xbps/raw/branch/stable/x86_64

Or install directly:

sudo xbps-install -S https://git.bongbetic.com/xavierk/Fenris-xbps/raw/branch/stable/x86_64

Publication Mechanism

1. Build: make package-xbps
2. Sign: make sign-xbps (or scripts/xbps-publish.sh handles this)
3. Publish: make xbps-publish
4. Verify: Check raw URL returns HTTP 200

The publication script (scripts/xbps-publish.sh) automates the full flow: build → sign → clone repo → add to index → sign repository → commit → push.

Dependencies for Subsequent Tickets

• Issue #86 (Publish validated package formats): Uses this publication mechanism for real Fenris packages instead of test artifacts.
• Issue #87 (Validate on Void machine): Uses the established repository URL and signing infrastructure for end-to-end validation.