diff --git a/docs/development/optional-agent-packages.md b/docs/development/optional-agent-packages.md index cd45f03ff5..c36b54a1d7 100644 --- a/docs/development/optional-agent-packages.md +++ b/docs/development/optional-agent-packages.md @@ -24,6 +24,16 @@ Client capability elements receive the Engine's selected UI locale through their English; the Engine does not translate package prompts or package-authored machine values. Locale changes reuse the existing `marinara-capability-props` event so an installed interface can rerender without an Engine restart. +### Delivery and caching + +Installed package files are served with strong validators derived from the manifest's per-file +SHA-256 hashes — the same values the Engine re-verifies the bytes against on every read. The +client bundle (`/api/capability-packages//client`) always revalidates (`no-cache` plus an +`ETag`), so an unchanged bundle answers `304 Not Modified` instead of re-downloading, while a +republished bundle is picked up immediately. Package asset requests that pin the installed +version with `?v=` are content-addressed and may be cached indefinitely +(`immutable`); requests without the pin keep always-revalidate semantics. + Capability API 1.1 adds a generic runtime facade to the server activation context. Packages can read the effective agent-debug state and write through the Engine's Pino logger, including explicit debug-mode overrides, without importing the diff --git a/package.json b/package.json index 480b045d1e..5a2f04c6e9 100644 --- a/package.json +++ b/package.json @@ -57,9 +57,10 @@ "regression:mari-instructions": "pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/mari-instructions-memory.regression.ts", "regression:mari-db-execution-security:run": "pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/mari-db-execution-security.regression.ts", "regression:mari-db-execution-security": "pnpm build:shared && pnpm regression:mari-db-execution-security:run", - "regression:issues": "pnpm regression:card-library-search && pnpm regression:persona-client:run && pnpm regression:chat-resource-drop && pnpm regression:avatar-delete && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/chat-html-newlines.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/open-issues.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/assigned-issue-sweep.regression.ts && pnpm regression:swarmui-timeout && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/stock-preset-protection.regression.ts && pnpm regression:mari-review-durability && pnpm regression:storage-writer-lock && pnpm regression:mari-preset-granular && pnpm regression:mari-instructions && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/bot-browser-route.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/janny-character-import.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/agent-activation.regression.ts && pnpm regression:agent-registry-hydration && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/profile-import-noodle.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/notification-sound.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/agent-catalog-kind-badges.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/file-backed-shutdown.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/autonomous-scheduler-gate.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/message-sharding.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/memory-recall-revectorize.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/env-watcher.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/extension-ipc.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/capability-package-lifecycle.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/capability-client-version-refresh.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/message-page-cache.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/chat-branch-lineage.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/conversation-game-slash.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/game-metadata-race.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/game-checkpoint-engine-state.regression.ts && pnpm regression:launcher-update && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/scene-video-range.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-prompt-context.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-documentation.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-fetch-tiers.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/entity-embedding-store.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-fetch-integration.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-relevance-names.regression.ts", + "regression:issues": "pnpm regression:card-library-search && pnpm regression:persona-client:run && pnpm regression:chat-resource-drop && pnpm regression:avatar-delete && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/chat-html-newlines.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/open-issues.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/assigned-issue-sweep.regression.ts && pnpm regression:swarmui-timeout && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/stock-preset-protection.regression.ts && pnpm regression:mari-review-durability && pnpm regression:storage-writer-lock && pnpm regression:mari-preset-granular && pnpm regression:mari-instructions && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/bot-browser-route.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/janny-character-import.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/agent-activation.regression.ts && pnpm regression:agent-registry-hydration && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/profile-import-noodle.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/notification-sound.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/agent-catalog-kind-badges.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/file-backed-shutdown.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/autonomous-scheduler-gate.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/message-sharding.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/memory-recall-revectorize.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/env-watcher.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/extension-ipc.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/capability-package-lifecycle.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/capability-client-version-refresh.regression.ts && pnpm regression:capability-cache && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/message-page-cache.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/chat-branch-lineage.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/conversation-game-slash.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/game-metadata-race.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/game-checkpoint-engine-state.regression.ts && pnpm regression:launcher-update && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/scene-video-range.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-prompt-context.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-documentation.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-fetch-tiers.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/entity-embedding-store.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-fetch-integration.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-relevance-names.regression.ts", "regression:launcher-update": "node ./scripts/regressions/launcher-env.regression.mjs && node ./scripts/regressions/launcher-update.regression.mjs && node ./scripts/regressions/dev-launcher-process.regression.mjs && node ./scripts/regressions/launcher-format-guard.regression.mjs && node ./scripts/check-windows-installer-layout.mjs", "regression:card-library-search": "pnpm build:shared && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/card-library-search.regression.ts", + "regression:capability-cache": "pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/capability-package-cache.regression.ts", "regression:chat-resource-drop": "pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/chat-resource-drop.regression.ts", "regression:gallery-delete": "pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/gallery-cascade-deletion.regression.ts", "regression:avatar-delete": "pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/avatar-file-deletion.regression.ts", diff --git a/packages/server/src/middleware/rate-limit.ts b/packages/server/src/middleware/rate-limit.ts index 6812944826..ca14730acc 100644 --- a/packages/server/src/middleware/rate-limit.ts +++ b/packages/server/src/middleware/rate-limit.ts @@ -62,6 +62,15 @@ const ROUTE_RULES: Array<{ pattern: RegExp; rule: RateLimitRule }> = [ // exploit the persistent storage path. 60/min covers React Query // refetches + legacy migrations of small extension lists comfortably. { pattern: /^\/api\/extensions(?:\/|\?|$)/, rule: { key: "extensions", limit: 60, windowMs: 60_000 } }, + // Package file serving (client bundles + declared assets) reads and + // hash-verifies from disk on every request; keep it out of the generous + // default bucket so a scripted loop can't turn that into cheap IO + // amplification. Normal loads fetch one bundle per installed package and + // revalidate with 304s afterwards, so 240/min leaves ample headroom. + { + pattern: /^\/api\/capability-packages\/[^/]+\/(?:client|assets)(?:\/|\?|$)/, + rule: { key: "capability-package-files", limit: 240, windowMs: 60_000 }, + }, ]; const buckets = new Map(); diff --git a/packages/server/src/routes/capability-packages.routes.ts b/packages/server/src/routes/capability-packages.routes.ts index 084e7bf2bc..846d5975ef 100644 --- a/packages/server/src/routes/capability-packages.routes.ts +++ b/packages/server/src/routes/capability-packages.routes.ts @@ -18,6 +18,20 @@ const packageParams = z.object({ .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/) .max(80), }); + +/** Strong ETag from the manifest-recorded sha256 — the same value the serve + * path re-verifies the bytes against, so the validator can never drift. */ +function packageFileEtag(sha256Hex: string): string { + return `"${sha256Hex}"`; +} + +function ifNoneMatchSatisfied(headerValue: string | undefined, etag: string): boolean { + if (!headerValue) return false; + if (headerValue.trim() === "*") return true; + // Weak comparison is fine for 304s: a W/-prefixed candidate with the same + // hash still identifies the same bytes here. + return headerValue.split(",").some((candidate) => candidate.trim().replace(/^W\//, "") === etag); +} const packageAssetParams = packageParams.extend({ "*": z.string().min(1).max(240) }); const packageVersion = z .string() @@ -75,20 +89,48 @@ export async function capabilityPackagesRoutes(app: FastifyInstance) { const { id } = packageParams.parse(request.params); const entrypoint = await capabilityPackageManager.clientEntrypoint(id); if (!entrypoint) return reply.status(404).send({ error: "Active client package not found" }); - reply.header("Content-Type", "text/javascript; charset=utf-8"); + // Deliberately NOT immutable, even though the URL carries ?v=: a package + // author (or the catalog) can republish the same version string with + // different bytes during development, and an immutable client bundle would + // pin the stale copy with no way to evict it short of a hard reload. + // no-cache + a strong ETag keeps "always revalidate" semantics while + // letting the revalidation answer 304 instead of re-sending the body. + const etag = packageFileEtag(entrypoint.sha256); reply.header("Cache-Control", "no-cache, must-revalidate"); + reply.header("ETag", etag); reply.header("X-Content-Type-Options", "nosniff"); + if (ifNoneMatchSatisfied(request.headers["if-none-match"], etag)) { + return reply.status(304).send(); + } + reply.header("Content-Type", "text/javascript; charset=utf-8"); return reply.send(await readFile(entrypoint.file)); }); - app.get<{ Params: { id: string; "*": string } }>("/:id/assets/*", async (request, reply) => { - const { id, "*": assetPath } = packageAssetParams.parse(request.params); - const asset = await capabilityPackageManager.browserTabAsset(id, assetPath); - if (!asset) return reply.status(404).send({ error: "Active package asset not found" }); - reply.header("Content-Type", asset.contentType); - reply.header("Cache-Control", "private, no-cache, must-revalidate"); - reply.header("X-Content-Type-Options", "nosniff"); - return reply.send(await readFile(asset.file)); - }); + app.get<{ Params: { id: string; "*": string }; Querystring: { v?: string } }>( + "/:id/assets/*", + async (request, reply) => { + const { id, "*": assetPath } = packageAssetParams.parse(request.params); + const asset = await capabilityPackageManager.browserTabAsset(id, assetPath); + if (!asset) return reply.status(404).send({ error: "Active package asset not found" }); + const etag = packageFileEtag(asset.sha256); + // A request that pins the installed version may cache the bytes forever: + // path + version + manifest hash identify them exactly. Any other request + // keeps today's always-revalidate behaviour byte-for-byte. + const requestedVersion = typeof request.query?.v === "string" ? request.query.v : null; + reply.header( + "Cache-Control", + requestedVersion === asset.installed.version + ? "public, max-age=31536000, immutable" + : "private, no-cache, must-revalidate", + ); + reply.header("ETag", etag); + reply.header("X-Content-Type-Options", "nosniff"); + if (ifNoneMatchSatisfied(request.headers["if-none-match"], etag)) { + return reply.status(304).send(); + } + reply.header("Content-Type", asset.contentType); + return reply.send(await readFile(asset.file)); + }, + ); app.post<{ Params: { id: string }; Body: { expectedVersion: string; expectedArtifactSha256: string } }>( "/:id/install", async (request, reply) => { diff --git a/packages/server/src/services/capability-packages/package-manager.service.ts b/packages/server/src/services/capability-packages/package-manager.service.ts index b8d83b4a51..dc94b5350d 100644 --- a/packages/server/src/services/capability-packages/package-manager.service.ts +++ b/packages/server/src/services/capability-packages/package-manager.service.ts @@ -818,8 +818,15 @@ export const capabilityPackageManager = { if (!installed || !isInstalledCapabilityReady(installed)) return null; const entrypoint = installed.manifest.entrypoints.client; if (!entrypoint) return null; + // The manifest-recorded hash doubles as a strong HTTP validator (ETag): it + // is the same value the read below re-verifies the bytes against. + const declaration = installed.manifest.files.find( + (item) => normalizeArchivePath(item.path) === normalizeArchivePath(entrypoint), + ); + if (!declaration) return null; return { installed, + sha256: declaration.sha256, file: await verifyInstalledPackageFile(installed, entrypoint), }; }, @@ -835,12 +842,14 @@ export const capabilityPackageManager = { } const iconPaths = installed.manifest.contributions?.homeBrowserTab?.iconPaths ?? []; if (!iconPaths.some((path) => normalizeArchivePath(path) === normalizedPath)) return null; - if (!installed.manifest.files.some((item) => normalizeArchivePath(item.path) === normalizedPath)) return null; + const declaration = installed.manifest.files.find((item) => normalizeArchivePath(item.path) === normalizedPath); + if (!declaration) return null; const contentType = BROWSER_TAB_ASSET_CONTENT_TYPES.get(extname(normalizedPath).toLowerCase()); if (!contentType) return null; return { installed, contentType, + sha256: declaration.sha256, file: await verifyBrowserTabAsset(installed, normalizedPath), }; }, diff --git a/scripts/regressions/capability-package-cache.regression.ts b/scripts/regressions/capability-package-cache.regression.ts new file mode 100644 index 0000000000..ade388e63c --- /dev/null +++ b/scripts/regressions/capability-package-cache.regression.ts @@ -0,0 +1,204 @@ +// ────────────────────────────────────────────── +// Regression: capability-package delivery cache validators (#5082) +// ────────────────────────────────────────────── +// Pins the HTTP caching contract for /api/capability-packages/:id/client and +// /:id/assets/*: a strong ETag derived from the manifest-recorded sha256, +// 304 on a matching If-None-Match, a DIFFERENT validator after an update, +// `no-cache` (never immutable) on the client bundle, and immutable asset +// responses only when the request pins the installed version with ?v=. +import assert from "node:assert/strict"; +import { createHash } from "node:crypto"; +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +const dataDir = mkdtempSync(join(tmpdir(), "marinara-capability-cache-")); +process.env.DATA_DIR = dataDir; + +const packagesRoot = join(dataDir, "capability-packages"); +const registryPath = join(packagesRoot, "installed.json"); + +const CLIENT_V1 = "// cache regression client v1\nexport {};\n"; +const CLIENT_V2 = "// cache regression client v2 — different bytes\nexport {};\n"; +// A 1×1 PNG; the asset route only serves manifest-declared image files. +const ICON = Buffer.from( + "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==", + "base64", +); + +const sha256 = (data: Buffer | string) => createHash("sha256").update(data).digest("hex"); + +function writeFixture(version: string, clientSource: string) { + const versionRoot = join(packagesRoot, "versions", "cache-probe", version); + mkdirSync(versionRoot, { recursive: true }); + writeFileSync(join(versionRoot, "client.js"), clientSource); + writeFileSync(join(versionRoot, "icon.png"), ICON); + const manifest = { + schemaVersion: 1, + id: "cache-probe", + name: "Cache Probe", + version, + description: "Capability package cache-validator regression fixture.", + engine: { min: "2.3.0", maxExclusive: "3.0.0" }, + kind: ["agent"], + entrypoints: { client: "client.js" }, + contributions: { + slots: ["home-browser-tab"], + homeBrowserTab: { label: "Cache Probe", iconPaths: ["icon.png"] }, + }, + files: [ + { path: "client.js", sha256: sha256(clientSource), bytes: Buffer.byteLength(clientSource) }, + { path: "icon.png", sha256: sha256(ICON), bytes: ICON.byteLength }, + ], + permissions: [], + restartRequired: false, + }; + writeFileSync(join(versionRoot, "manifest.json"), JSON.stringify(manifest, null, 2)); + const record = { + id: "cache-probe", + version, + manifest, + installedAt: "2026-08-15T00:00:00.000Z", + status: "active", + error: null, + readiness: "ready", + readinessError: null, + legacy: false, + }; + mkdirSync(packagesRoot, { recursive: true }); + writeFileSync(registryPath, JSON.stringify({ schemaVersion: 1, packages: [record] }, null, 2)); + return manifest; +} + +async function main() { + const manifestV1 = writeFixture("1.0.0", CLIENT_V1); + + // fastify is a server-workspace dependency; under pnpm's strict layout it is + // not resolvable from scripts/, so resolve it from the server package. + const { createRequire } = await import("node:module"); + const serverRequire = createRequire( + new URL("../../packages/server/src/routes/capability-packages.routes.ts", import.meta.url), + ); + const fastify = serverRequire("fastify") as typeof import("fastify").default; + const { capabilityPackagesRoutes } = await import( + "../../packages/server/src/routes/capability-packages.routes.js" + ); + const { rateLimitHook, resetRateLimitBucketsForTests } = await import( + "../../packages/server/src/middleware/rate-limit.js" + ); + resetRateLimitBucketsForTests(); + const app = fastify({ logger: false }); + app.addHook("onRequest", rateLimitHook); + await app.register(capabilityPackagesRoutes, { prefix: "/api/capability-packages" }); + + const clientEtag = `"${manifestV1.files[0]!.sha256}"`; + const iconEtag = `"${manifestV1.files[1]!.sha256}"`; + + // ── /client: 200 with a strong manifest-hash ETag, always-revalidate ── + const first = await app.inject({ method: "GET", url: "/api/capability-packages/cache-probe/client?v=1.0.0" }); + assert.equal(first.statusCode, 200); + assert.equal(first.headers.etag, clientEtag, "client ETag must be the manifest sha256"); + assert.equal(first.headers["cache-control"], "no-cache, must-revalidate", "client bundle must never be immutable"); + assert.equal(first.headers["x-content-type-options"], "nosniff"); + assert.equal(first.body, CLIENT_V1); + // Package file serving sits in its own rate-limit bucket, not the generous + // default one (CodeQL: file-system access without route-scoped limiting). + assert.equal( + first.headers["ratelimit-limit"], + "240", + "package file routes must match the capability-package-files rate-limit rule", + ); + + // ── /client: matching If-None-Match answers 304 with no body ── + for (const candidate of [clientEtag, `W/${clientEtag}`, `"other", ${clientEtag}`]) { + const revalidated = await app.inject({ + method: "GET", + url: "/api/capability-packages/cache-probe/client?v=1.0.0", + headers: { "if-none-match": candidate }, + }); + assert.equal(revalidated.statusCode, 304, `304 expected for If-None-Match: ${candidate}`); + assert.equal(revalidated.body, ""); + assert.equal(revalidated.headers.etag, clientEtag); + assert.equal(revalidated.headers["x-content-type-options"], "nosniff", "nosniff must survive the 304 early return"); + } + + // ── /client: a non-matching validator still gets the full body ── + const mismatched = await app.inject({ + method: "GET", + url: "/api/capability-packages/cache-probe/client", + headers: { "if-none-match": `"${"0".repeat(64)}"` }, + }); + assert.equal(mismatched.statusCode, 200); + assert.equal(mismatched.body, CLIENT_V1); + + // ── assets: always-revalidate without ?v=, immutable only when ?v= matches ── + const assetPlain = await app.inject({ method: "GET", url: "/api/capability-packages/cache-probe/assets/icon.png" }); + assert.equal(assetPlain.statusCode, 200); + assert.equal(assetPlain.headers["cache-control"], "private, no-cache, must-revalidate"); + assert.equal(assetPlain.headers.etag, iconEtag); + assert.equal(assetPlain.headers["ratelimit-limit"], "240", "asset serving shares the package-files rate bucket"); + + const assetPinned = await app.inject({ + method: "GET", + url: "/api/capability-packages/cache-probe/assets/icon.png?v=1.0.0", + }); + assert.equal(assetPinned.statusCode, 200); + assert.equal( + assetPinned.headers["cache-control"], + "public, max-age=31536000, immutable", + "a version-pinned asset request is content-addressed and may cache forever", + ); + + const assetWrongPin = await app.inject({ + method: "GET", + url: "/api/capability-packages/cache-probe/assets/icon.png?v=9.9.9", + }); + assert.equal(assetWrongPin.headers["cache-control"], "private, no-cache, must-revalidate"); + + const assetRevalidated = await app.inject({ + method: "GET", + url: "/api/capability-packages/cache-probe/assets/icon.png", + headers: { "if-none-match": iconEtag }, + }); + assert.equal(assetRevalidated.statusCode, 304); + assert.equal( + assetRevalidated.headers["x-content-type-options"], + "nosniff", + "nosniff must survive the 304 early return", + ); + + // ── update: new bytes under a new version yield a NEW validator, and the + // old validator no longer short-circuits to 304 ── + const manifestV2 = writeFixture("1.0.1", CLIENT_V2); + const updatedEtag = `"${manifestV2.files[0]!.sha256}"`; + assert.notEqual(updatedEtag, clientEtag); + const afterUpdate = await app.inject({ + method: "GET", + url: "/api/capability-packages/cache-probe/client?v=1.0.1", + headers: { "if-none-match": clientEtag }, + }); + assert.equal(afterUpdate.statusCode, 200, "a stale validator must not mask an updated bundle"); + assert.equal(afterUpdate.headers.etag, updatedEtag); + assert.equal(afterUpdate.body, CLIENT_V2); + + // ── existing failure modes preserved ── + const unknown = await app.inject({ method: "GET", url: "/api/capability-packages/nope/client" }); + assert.equal(unknown.statusCode, 404); + const undeclared = await app.inject({ + method: "GET", + url: "/api/capability-packages/cache-probe/assets/manifest.json", + }); + assert.equal(undeclared.statusCode, 404, "only declared image assets are servable"); + + await app.close(); + console.log("capability-package-cache regression passed"); +} + +main() + .then(() => { + rmSync(dataDir, { recursive: true, force: true }); + }) + .catch((error) => { + console.error(error); + process.exitCode = 1; + });