fix: working generic refresh webhook; document raw as the backend-private asset slot (Phase 7 PR A)

[dopry]

Summary

First of the three Phase 7 PRs (backend abstraction → resolution pipeline → HTTP split). This one clarifies the backend↔core contract and fixes a broken endpoint; HTTP behavior of all download/update routes is unchanged (Phase 1 contract suite passes untouched).

Backend contract: raw is the backend-private slot, typed via TRaw

An asset is only ever served by the backend that created it — serveAsset/getAssetStream are abstract Backend methods that core always delegates to — so per-backend serving state is that backend's internal detail, not public model surface. The PR encodes that instead of adding new public fields:

• PecansAssetDTO.raw is documented as the backend-private slot: the backend that normalizes an asset may stash whatever it needs there, and core and other consumers must not interpret it. This is the pattern the codebase has had since 1.x, now stated as a rule.
• PecansAssetDTO<TRaw = unknown> / PecansAsset<TRaw = unknown> / Backend<TRaw = unknown>: a backend declares its payload type once (PecansGitHubBackend extends Backend<GithubReleaseAsset>) and gets fully typed raw reads back in serveAsset/getAssetStream — no subclassing of the model needed. At the neutral default raw is unknown, so consumers must narrow instead of dot-accessing what used to be any. Type-level change only; zero runtime difference. (Type-level break: code reading asset.raw.foo against the neutral type no longer compiles — that's the hint safety this buys.)
• The GitHub backend's reads of its own raw gain clear missing-field errors (Asset 123 has no browser_download_url in its raw payload) instead of crashing with Cannot read properties of undefined on malformed assets.

An earlier iteration of this PR added public downloadUrl/apiUrl fields to the DTO; review discussion concluded that was itself a leaky abstraction (core never needs them, and they would grow the already-serialized /api/versions asset JSON), so it was reverted in favor of the documented-opaque-raw contract.

Fix: generic refresh webhook could never authenticate

The base Backend.getRefreshWebhookMiddleware compared the stored secret hash against req.params.secret — which is never populated on use()-mounted middleware, so any request with a configured refreshSecret failed. Now:

• POST-only on the watched path (matching the GitHub webhook middleware); other methods fall through, so crawlers following a shared ?secret= link can't trigger refreshes (Copilot review finding).
• The secret arrives via an X-Pecans-Secret header or ?secret= query parameter (the middleware has no route params to read).
• Comparison is constant-time (crypto.timingSafeEqual over sha256 digests).
• Mismatch → 403 via a new ForbiddenError (exported, slots into the Phase 6 error hierarchy); success → 200 {"refreshed": true}.
• No refreshSecret configured → pass-through (endpoint stays disabled), unchanged.

The GitHub backend's override (signed-payload verification via @octokit/webhooks) is untouched. Documented in a new README "Cache-refresh webhook" section.

Verification

• npm test: 31 files / 717 passed (new coverage: webhook middleware unit + e2e tests through the router's error handler, POST-only gate, raw-passthrough and missing-url error pins)
• lint, typecheck, format, build green
• packed tarball smoke-tested from CJS and ESM, plus a strict-mode TS consumer check: TRaw inference works, neutral raw is unknown (dot access fails to compile), PecansGitHubBackend still satisfies the neutral Backend slot

🤖 Generated with Claude Code

https://claude.ai/code/session_015zUyj4PpSog9RkrYxzFRhM

[Copilot]

Pull request overview

This PR makes the backend↔core contract more explicit by adding explicit asset URLs to PecansAssetDTO, and fixes the generic (non-GitHub) cache-refresh webhook authentication so it can actually be used when mounted via use().

Changes:

• Add downloadUrl (public redirect target) and apiUrl (authenticated fetch target) to PecansAssetDTO, with a documented compatibility fallback to the GitHub-shaped raw payload (planned removal in 3.0).
• Update the GitHub backend to populate and consume these explicit URLs (including erroring when missing), reducing downstream coupling to GitHub REST shapes.
• Fix the base Backend.getRefreshWebhookMiddleware to authenticate via X-Pecans-Secret header or ?secret= query param using constant-time comparison, returning 403 via a new ForbiddenError, and returning 200 { refreshed: true } on success; add docs + broaden test harness to support non-GitHub backends.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
test/unit/PecansAsset.spec.ts	Adds unit coverage for downloadUrl/apiUrl propagation and raw-payload fallback behavior.
test/unit/github.spec.ts	Updates GitHub backend tests to validate redirects/fetches use explicit URLs with raw fallbacks and missing-URL errors.
test/unit/backend-complete.spec.ts	Updates base-backend webhook middleware tests for header/query secret auth, 403 behavior, and 200 JSON success response.
test/integration/webhook.spec.ts	Adds integration tests covering the generic refresh webhook behavior end-to-end (non-GitHub backend).
test/harness.ts	Generalizes configurePecansTestApp to accept any Backend, enabling non-GitHub integration testing.
src/models/PecansAsset.ts	Introduces downloadUrl/apiUrl fields on asset DTO/model with compatibility fallback from raw.
src/errors.ts	Adds ForbiddenError (HTTP 403) to the typed error hierarchy.
src/backends/github.ts	Populates and uses explicit asset URLs in normalizeAsset, serveAsset, and getAssetStream with raw fallbacks.
src/backends/backend.ts	Fixes refresh webhook secret extraction for use()-mounted middleware, adds constant-time verification, and responds 200 JSON on refresh.
README.md	Documents the cache-refresh webhook for GitHub and non-GitHub backends (header/query secret, 200/403 responses).

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.