ci: breaking-change gate on api-description.yaml (oasdiff)

[rubenhensen]

Same gate as pg-pkg's: diff api-description.yaml against main with oasdiff in CI and fail on breaking changes. Cryptify's routes are unversioned, so every breaking diff fails hard. First step: verify the spec actually matches the mounted routes (the audit noted drift), then ratchet.

Part of encryption4all/postguard#247 (workstream C).

[rubenhensen]

/dobby please pick this up — spec in the issue body: first verify api-description.yaml matches the actually mounted routes (audit noted drift), then add an oasdiff breaking-change gate. Known App limitation: you can't push .github/workflows/ — deliver the workflow YAML in a PR comment and a maintainer will land it on your branch, same as wave 1. Part of encryption4all/postguard#247 wave 2.

[dobby-coder]

On it! I'll start by auditing api-description.yaml against the actually mounted routes to check for the drift the audit flagged, then add an oasdiff breaking-change gate. Since the App can't push to .github/workflows/, I'll deliver that workflow YAML in a follow-up comment here for a maintainer to land, same as wave 1 — the rest of the changes will go up as a draft PR.

[dobby-coder]

Done — cryptify#200 is out of draft and ready for you.

I rule-checked the diff (14 applicable rules) and found one breach: the spec never documented that Content-Range's end byte is exclusive, even though upload_chunk enforces exactly that. I fixed it directly on the branch (2190e96) along with four other spec/handler mismatches I verified while reviewing — a missing Accept-Ranges case, an undocumented 500 on range downloads, a second cause for the init 400, and a missing null case on StagingPreview.confirmation. CI is fully green (fmt, clippy, 154 tests, both Docker builds) and the spec still validates as OpenAPI 3.0.3.

Two things left for you:

• One non-blocking inline suggestion on the Authorization header parameter — worth deciding alongside the /usage endpoint, which documents the same credential the other way.
• The download Content-Type mismatch (application/octet-stream vs application/cryptify+octet-stream) is still open from the PR body — separate PR territory.

For the gate itself: the workflow YAML is in a PR comment (App can't push .github/workflows/), and I reviewed it — review: false so nothing goes to oasdiff.com, action tag pinned, no run: blocks. Landing order is right: merge this PR first, then add the workflow on main, since truing up the drifted spec is itself a breaking change that would otherwise fail the gate's first run.