onbuzz 4.9.11 → 4.9.13

package/src/interfaces/__tests__/webServer.marketplace.test.js

@@ -0,0 +1,629 @@
+/**
+ * Tests for the marketplace proxy router on the local CLI server.
+ *
+ * These cover six behavior categories that together protect the install
+ * flow end-to-end:
+ *
+ *   A. Proxy round-trip — method, body, and response are passed through
+ *      byte-identically. The browser sees what upstream returned.
+ *
+ *   B. Auth header forwarding — Authorization (the JWT bearer) is
+ *      forwarded to upstream verbatim. The local server never
+ *      synthesises auth and never strips it.
+ *
+ *   C. Integrity mismatch — when upstream's X-Content-Hash header does
+ *      not match the SHA-256 of the downloaded body, the proxy MUST
+ *      respond 502 with `error: 'integrity_mismatch'` and populate
+ *      expected/actual hash + byte counts. A corrupted body must NEVER
+ *      reach the renderer as 200-OK.
+ *
+ *   D. Content-Length mismatch — Content-Length: 1000 + 500-byte body
+ *      → 502 `content_length_mismatch`. Client must NOT see a
+ *      truncated success body.
+ *
+ *   E. Stream truncation — mid-stream upstream error surfaces as 502
+ *      `stream_truncated`. Client does NOT receive a partial 200.
+ *
+ *   F. Error mapping — upstream 404/401/500 are passed through with
+ *      their status + body so the renderer's error toasts read the
+ *      same as a direct call would.
+ *
+ * Pure DI — the router is constructed with a `fetchImpl` stub, no
+ * real HTTP, no environment dependence.
+ */
+
+import { describe, test, expect, jest, beforeEach } from '@jest/globals';
+import express from 'express';
+import { createServer } from 'http';
+import crypto from 'crypto';
+import {
+  createMarketplaceRouter,
+  parseContentHashHeader,
+  verifyDownloadBytes,
+  INTEGRITY_ERROR_CODES,
+  __test__,
+} from '../marketplaceRoutes.js';
+
+const UPSTREAM = 'https://marketplace.test';
+const SAMPLE_JWT = 'eyJ.sample.jwt';
+
+// ──────────────────────────────────────────────────────────────────
+// helpers
+// ──────────────────────────────────────────────────────────────────
+
+/**
+ * Build a minimal fetch-compatible Response-like object for the stub.
+ * Real WHATWG Response would also work, but constructing it manually
+ * lets us set Content-Length to a deliberately wrong value (which the
+ * spec Response constructor would silently overwrite) — that's exactly
+ * the corner we need to test.
+ */
+function makeUpstreamResponse({ status = 200, headers = {}, body = '', bodyBytes = null, throwsOnRead = false } = {}) {
+  // Normalise header keys to lowercase to mimic WHATWG Headers behaviour.
+  const lower = {};
+  for (const [k, v] of Object.entries(headers)) lower[k.toLowerCase()] = v;
+  const buf = bodyBytes ?? Buffer.from(body);
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    headers: {
+      get: (k) => {
+        const v = lower[k.toLowerCase()];
+        return v === undefined ? null : v;
+      },
+    },
+    async arrayBuffer() {
+      if (throwsOnRead) throw new Error('upstream stream aborted');
+      return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+    },
+    async text() {
+      if (throwsOnRead) throw new Error('upstream stream aborted');
+      return buf.toString('utf8');
+    },
+    async json() {
+      if (throwsOnRead) throw new Error('upstream stream aborted');
+      return JSON.parse(buf.toString('utf8'));
+    },
+  };
+}
+
+function sha256Hex(buf) {
+  return crypto.createHash('sha256').update(Buffer.isBuffer(buf) ? buf : Buffer.from(buf)).digest('hex');
+}
+
+async function startServer(router) {
+  const app = express();
+  app.use(express.json());
+  app.use('/api/marketplace', router);
+  const server = createServer(app);
+  await new Promise(r => server.listen(0, r));
+  const port = server.address().port;
+  return {
+    server,
+    baseUrl: `http://127.0.0.1:${port}`,
+    stop: () => new Promise(r => server.close(r)),
+  };
+}
+
+function buildRouter({ fetchImpl, logger = { info: () => {}, warn: () => {}, error: () => {} } } = {}) {
+  return createMarketplaceRouter({
+    upstreamBaseUrl: UPSTREAM,
+    fetchImpl,
+    logger,
+  });
+}
+
+// ──────────────────────────────────────────────────────────────────
+// Pure-function unit tests for the integrity helpers
+// ──────────────────────────────────────────────────────────────────
+
+describe('parseContentHashHeader', () => {
+  test('accepts canonical "sha256-<hex>"', () => {
+    const hex = sha256Hex('hello');
+    expect(parseContentHashHeader(`sha256-${hex}`)).toBe(hex);
+  });
+
+  test('accepts upper-case sha256 prefix', () => {
+    const hex = sha256Hex('hello');
+    expect(parseContentHashHeader(`SHA256-${hex.toUpperCase()}`)).toBe(hex);
+  });
+
+  test('accepts bare hex (no prefix)', () => {
+    const hex = sha256Hex('x');
+    expect(parseContentHashHeader(hex)).toBe(hex);
+  });
+
+  test('returns null for missing / non-hex / empty', () => {
+    expect(parseContentHashHeader(undefined)).toBeNull();
+    expect(parseContentHashHeader('')).toBeNull();
+    expect(parseContentHashHeader('sha256-not-hex')).toBeNull();
+    expect(parseContentHashHeader('!')).toBeNull();
+  });
+});
+
+describe('verifyDownloadBytes', () => {
+  const body = Buffer.from('{"hello":"world"}', 'utf8');
+  const correctHash = sha256Hex(body);
+
+  test('ok when hash + length both match', () => {
+    const r = verifyDownloadBytes(body, { expectedHash: correctHash, expectedBytes: body.length });
+    expect(r.ok).toBe(true);
+    expect(r.actualHash).toBe(correctHash);
+    expect(r.actualBytes).toBe(body.length);
+  });
+
+  test('ok when only one expectation is given (other is null)', () => {
+    expect(verifyDownloadBytes(body, { expectedHash: correctHash, expectedBytes: null }).ok).toBe(true);
+    expect(verifyDownloadBytes(body, { expectedHash: null, expectedBytes: body.length }).ok).toBe(true);
+  });
+
+  test('flags content_length_mismatch before integrity_mismatch', () => {
+    const r = verifyDownloadBytes(body, { expectedHash: 'deadbeef', expectedBytes: 9999 });
+    expect(r.ok).toBe(false);
+    expect(r.code).toBe(INTEGRITY_ERROR_CODES.CONTENT_LENGTH_MISMATCH);
+    expect(r.expectedBytes).toBe(9999);
+    expect(r.actualBytes).toBe(body.length);
+  });
+
+  test('flags integrity_mismatch when hash differs and length is fine', () => {
+    const r = verifyDownloadBytes(body, { expectedHash: 'deadbeef', expectedBytes: body.length });
+    expect(r.ok).toBe(false);
+    expect(r.code).toBe(INTEGRITY_ERROR_CODES.INTEGRITY_MISMATCH);
+    expect(r.expectedHash).toBe('deadbeef');
+    expect(r.actualHash).toBe(correctHash);
+  });
+});
+
+// ──────────────────────────────────────────────────────────────────
+// A. Proxy round-trip — body byte-identical, method & path correct
+// ──────────────────────────────────────────────────────────────────
+
+describe('marketplace proxy — round-trip', () => {
+  test('GET /items forwards query string + returns upstream JSON byte-identical', async () => {
+    const upstreamBody = { success: true, items: [{ id: 'a', name: 'A' }, { id: 'b', name: 'B' }], page: 2 };
+    const fetchImpl = jest.fn().mockResolvedValue(makeUpstreamResponse({
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(upstreamBody),
+    }));
+    const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+    try {
+      const res = await fetch(`${baseUrl}/api/marketplace/items?q=foo&type=skill&page=2&limit=10`);
+      expect(res.status).toBe(200);
+      expect(await res.json()).toEqual(upstreamBody);
+
+      // Upstream was hit with the full querystring + GET
+      expect(fetchImpl).toHaveBeenCalledTimes(1);
+      const [calledUrl, calledInit] = fetchImpl.mock.calls[0];
+      expect(calledUrl).toBe(`${UPSTREAM}/api/items?q=foo&type=skill&page=2&limit=10`);
+      expect(calledInit.method).toBe('GET');
+    } finally { await stop(); }
+  });
+
+  test('POST /items forwards the JSON body verbatim', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue(makeUpstreamResponse({
+      status: 200,
+      body: JSON.stringify({ success: true, item: { id: 'new' } }),
+    }));
+    const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+    const payload = {
+      type: 'skill',
+      name: 'Test Skill',
+      description: 'hi',
+      tags: ['ai', 'utility'],
+      content: { sections: [{ name: 's1' }] },
+      metadata: { difficulty: 'easy' },
+      authorName: 'Tester',
+    };
+
+    try {
+      const res = await fetch(`${baseUrl}/api/marketplace/items`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+      });
+      expect(res.status).toBe(200);
+
+      const [calledUrl, calledInit] = fetchImpl.mock.calls[0];
+      expect(calledUrl).toBe(`${UPSTREAM}/api/items`);
+      expect(calledInit.method).toBe('POST');
+      expect(JSON.parse(calledInit.body)).toEqual(payload);
+    } finally { await stop(); }
+  });
+
+  test('PUT /items/:id and DELETE /items/:id reach the right upstream path', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue(makeUpstreamResponse({
+      status: 200, body: JSON.stringify({ success: true }),
+    }));
+    const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+    try {
+      await fetch(`${baseUrl}/api/marketplace/items/abc-123`, {
+        method: 'PUT', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name: 'New' }),
+      });
+      expect(fetchImpl.mock.calls[0][0]).toBe(`${UPSTREAM}/api/items/abc-123`);
+      expect(fetchImpl.mock.calls[0][1].method).toBe('PUT');
+
+      await fetch(`${baseUrl}/api/marketplace/items/abc-123`, { method: 'DELETE' });
+      expect(fetchImpl.mock.calls[1][0]).toBe(`${UPSTREAM}/api/items/abc-123`);
+      expect(fetchImpl.mock.calls[1][1].method).toBe('DELETE');
+    } finally { await stop(); }
+  });
+
+  test('POST /items/:id/rate forwards body and reaches the rate path', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue(makeUpstreamResponse({
+      status: 200, body: JSON.stringify({ success: true, rating_avg: 4.5 }),
+    }));
+    const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+    try {
+      await fetch(`${baseUrl}/api/marketplace/items/xyz/rate`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ rating: 5, review: 'great', userName: 'me' }),
+      });
+      expect(fetchImpl.mock.calls[0][0]).toBe(`${UPSTREAM}/api/items/xyz/rate`);
+      expect(JSON.parse(fetchImpl.mock.calls[0][1].body)).toEqual({ rating: 5, review: 'great', userName: 'me' });
+    } finally { await stop(); }
+  });
+});
+
+// ──────────────────────────────────────────────────────────────────
+// B. Auth header forwarding
+// ──────────────────────────────────────────────────────────────────
+
+describe('marketplace proxy — auth forwarding', () => {
+  test('Authorization header is forwarded verbatim to upstream', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue(makeUpstreamResponse({
+      status: 200, body: JSON.stringify({ success: true, items: [] }),
+    }));
+    const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+    try {
+      await fetch(`${baseUrl}/api/marketplace/items`, {
+        headers: { 'Authorization': `Bearer ${SAMPLE_JWT}` },
+      });
+      const headers = fetchImpl.mock.calls[0][1].headers;
+      expect(headers['Authorization']).toBe(`Bearer ${SAMPLE_JWT}`);
+    } finally { await stop(); }
+  });
+
+  test('no Authorization header forwarded when caller has none', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue(makeUpstreamResponse({
+      status: 200, body: JSON.stringify({ success: true, items: [] }),
+    }));
+    const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+    try {
+      await fetch(`${baseUrl}/api/marketplace/items`);
+      const headers = fetchImpl.mock.calls[0][1].headers;
+      expect(headers['Authorization']).toBeUndefined();
+    } finally { await stop(); }
+  });
+
+  test('Authorization forwarded on POST /items (publish path)', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue(makeUpstreamResponse({
+      status: 200, body: JSON.stringify({ success: true, item: { id: 'x' } }),
+    }));
+    const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+    try {
+      await fetch(`${baseUrl}/api/marketplace/items`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${SAMPLE_JWT}` },
+        body: JSON.stringify({ type: 'skill', name: 'X' }),
+      });
+      expect(fetchImpl.mock.calls[0][1].headers['Authorization']).toBe(`Bearer ${SAMPLE_JWT}`);
+    } finally { await stop(); }
+  });
+});
+
+// ──────────────────────────────────────────────────────────────────
+// C + D. Integrity & Content-Length verification on /items/:id/download
+// ──────────────────────────────────────────────────────────────────
+
+describe('marketplace proxy — download integrity', () => {
+  test('passes verified body + Content-Hash + X-Integrity-Verified=true on match', async () => {
+    const body = Buffer.from(JSON.stringify({ name: 'My Skill', sections: [] }), 'utf8');
+    const hex  = sha256Hex(body);
+
+    const fetchImpl = jest.fn().mockResolvedValue(makeUpstreamResponse({
+      status: 200,
+      bodyBytes: body,
+      headers: {
+        'content-type':   'application/json',
+        'content-length': String(body.length),
+        'x-content-hash': `sha256-${hex}`,
+      },
+    }));
+    const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+    try {
+      const res = await fetch(`${baseUrl}/api/marketplace/items/abc/download`);
+      expect(res.status).toBe(200);
+      expect(res.headers.get('x-integrity-verified')).toBe('true');
+      expect(res.headers.get('x-content-hash')).toBe(`sha256-${hex}`);
+      expect(res.headers.get('content-length')).toBe(String(body.length));
+      const back = Buffer.from(await res.arrayBuffer());
+      expect(back.equals(body)).toBe(true);
+    } finally { await stop(); }
+  });
+
+  test('502 integrity_mismatch when upstream hash header is wrong', async () => {
+    const body = Buffer.from(JSON.stringify({ name: 'Tampered' }), 'utf8');
+    const realHex = sha256Hex(body);
+    const wrongHex = 'deadbeef'.repeat(8);
+
+    const fetchImpl = jest.fn().mockResolvedValue(makeUpstreamResponse({
+      status: 200,
+      bodyBytes: body,
+      headers: {
+        'content-type':   'application/json',
+        'content-length': String(body.length),
+        'x-content-hash': `sha256-${wrongHex}`,
+      },
+    }));
+    const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+    try {
+      const res = await fetch(`${baseUrl}/api/marketplace/items/abc/download`);
+      expect(res.status).toBe(502);
+      const j = await res.json();
+      expect(j.error).toBe('integrity_mismatch');
+      expect(j.expectedHash).toBe(wrongHex);
+      expect(j.actualHash).toBe(realHex);
+      expect(j.expectedBytes).toBe(body.length);
+      expect(j.actualBytes).toBe(body.length);
+      // Client must NOT have received the body.
+      expect(res.headers.get('x-integrity-verified')).not.toBe('true');
+    } finally { await stop(); }
+  });
+
+  test('502 content_length_mismatch when upstream Content-Length is wrong', async () => {
+    const body = Buffer.from('a'.repeat(500), 'utf8');
+    const hex = sha256Hex(body);
+
+    const fetchImpl = jest.fn().mockResolvedValue(makeUpstreamResponse({
+      status: 200,
+      bodyBytes: body,
+      headers: {
+        'content-type':   'application/octet-stream',
+        'content-length': '1000',                // wrong: claims 1000
+        'x-content-hash': `sha256-${hex}`,
+      },
+    }));
+    const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+    try {
+      const res = await fetch(`${baseUrl}/api/marketplace/items/abc/download`);
+      expect(res.status).toBe(502);
+      const j = await res.json();
+      expect(j.error).toBe('content_length_mismatch');
+      expect(j.expectedBytes).toBe(1000);
+      expect(j.actualBytes).toBe(500);
+    } finally { await stop(); }
+  });
+
+  test('legacy upstream (no integrity headers) passes through with X-Integrity-Verified=false', async () => {
+    const body = Buffer.from('{"legacy":true}', 'utf8');
+    const fetchImpl = jest.fn().mockResolvedValue(makeUpstreamResponse({
+      status: 200,
+      bodyBytes: body,
+      headers: { 'content-type': 'application/json' },
+    }));
+    const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+    try {
+      const res = await fetch(`${baseUrl}/api/marketplace/items/legacy/download`);
+      expect(res.status).toBe(200);
+      expect(res.headers.get('x-integrity-verified')).toBe('false');
+      const back = Buffer.from(await res.arrayBuffer());
+      expect(back.equals(body)).toBe(true);
+    } finally { await stop(); }
+  });
+});
+
+// ──────────────────────────────────────────────────────────────────
+// E. Stream truncation
+// ──────────────────────────────────────────────────────────────────
+
+describe('marketplace proxy — stream truncation', () => {
+  test('upstream errors mid-stream → 502 stream_truncated, NOT 200 partial', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue(makeUpstreamResponse({
+      status: 200,
+      headers: {
+        'content-type':   'application/json',
+        'content-length': '500',
+        'x-content-hash': `sha256-${sha256Hex('does not matter')}`,
+      },
+      throwsOnRead: true,
+    }));
+    const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+    try {
+      const res = await fetch(`${baseUrl}/api/marketplace/items/abc/download`);
+      expect(res.status).toBe(502);
+      const j = await res.json();
+      expect(j.error).toBe('stream_truncated');
+      expect(typeof j.details).toBe('string');
+      // Never integrity_verified
+      expect(res.headers.get('x-integrity-verified')).not.toBe('true');
+    } finally { await stop(); }
+  });
+
+  test('upstream network failure on download → 502 upstream_unreachable', async () => {
+    const fetchImpl = jest.fn().mockRejectedValue(new Error('ECONNREFUSED'));
+    const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+    try {
+      const res = await fetch(`${baseUrl}/api/marketplace/items/abc/download`);
+      expect(res.status).toBe(502);
+      const j = await res.json();
+      expect(j.error).toBe('upstream_unreachable');
+    } finally { await stop(); }
+  });
+});
+
+// ──────────────────────────────────────────────────────────────────
+// F. Error mapping
+// ──────────────────────────────────────────────────────────────────
+
+describe('marketplace proxy — error mapping', () => {
+  test.each([
+    [404, { error: 'not found' }],
+    [401, { error: 'unauthorized' }],
+    [500, { error: 'oops' }],
+  ])('upstream %i is preserved as-is on /items/:id', async (status, body) => {
+    const fetchImpl = jest.fn().mockResolvedValue(makeUpstreamResponse({
+      status,
+      body: JSON.stringify(body),
+      headers: { 'content-type': 'application/json' },
+    }));
+    const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+    try {
+      const res = await fetch(`${baseUrl}/api/marketplace/items/missing`);
+      expect(res.status).toBe(status);
+      expect(await res.json()).toEqual(body);
+    } finally { await stop(); }
+  });
+
+  test('upstream 404 on download is preserved (no integrity check on error body)', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue(makeUpstreamResponse({
+      status: 404,
+      body: JSON.stringify({ error: 'not found' }),
+      headers: { 'content-type': 'application/json' },
+    }));
+    const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+    try {
+      const res = await fetch(`${baseUrl}/api/marketplace/items/missing/download`);
+      expect(res.status).toBe(404);
+      expect(await res.json()).toEqual({ error: 'not found' });
+    } finally { await stop(); }
+  });
+
+  test('upstream network failure on a JSON endpoint → 502 upstream_unreachable', async () => {
+    const fetchImpl = jest.fn().mockRejectedValue(new Error('ENOTFOUND'));
+    const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+    try {
+      const res = await fetch(`${baseUrl}/api/marketplace/items`);
+      expect(res.status).toBe(502);
+      const j = await res.json();
+      expect(j.error).toBe('upstream_unreachable');
+      expect(j.details).toBe('ENOTFOUND');
+    } finally { await stop(); }
+  });
+});
+
+// ──────────────────────────────────────────────────────────────────
+// G. token_expired / reauth code surface — body byte-identical
+//    forwarding so the web-UI guard can discriminate by `code`.
+//
+//    Marketplace auth middleware returns one of:
+//      401 { error: 'Token expired',           code: 'token_expired'  }
+//      401 { error: 'Invalid token',           code: 'invalid_token'  }
+//      401 { error: 'Authentication required', code: 'no_token'       }
+//    The proxy MUST forward both the 401 status AND the body verbatim
+//    so the renderer's withReauthGuard sees `code` intact. Only
+//    'token_expired' triggers the reauth modal; the other two are
+//    real auth failures the user has to resolve explicitly.
+// ──────────────────────────────────────────────────────────────────
+
+describe('marketplace proxy — token_expired / reauth code surface', () => {
+  test.each([
+    ['token_expired',  'Token expired'],
+    ['invalid_token',  'Invalid token'],
+    ['no_token',       'Authentication required'],
+  ])('upstream 401 { code: %s } is forwarded byte-identical on JSON endpoints',
+    async (code, errorMsg) => {
+      const upstreamBody = { error: errorMsg, code };
+      const upstreamJson = JSON.stringify(upstreamBody);
+      const fetchImpl = jest.fn().mockResolvedValue(makeUpstreamResponse({
+        status: 401,
+        body: upstreamJson,
+        headers: { 'content-type': 'application/json' },
+      }));
+      const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+      try {
+        const res = await fetch(`${baseUrl}/api/marketplace/items`, {
+          headers: { 'Authorization': `Bearer ${SAMPLE_JWT}` },
+        });
+        // Status forwarded as 401 (NOT coalesced to 502/500).
+        expect(res.status).toBe(401);
+        const j = await res.json();
+        // Body byte-identical: both `error` and `code` survive.
+        expect(j).toEqual(upstreamBody);
+        expect(j.code).toBe(code);
+        expect(j.error).toBe(errorMsg);
+      } finally { await stop(); }
+    }
+  );
+
+  test('upstream 401 with NO code field (legacy upstream) is forwarded unchanged', async () => {
+    // Some non-marketplace upstreams (or older deployments) return 401
+    // without a `code` discriminator. The proxy must not invent one and
+    // must not strip the existing error field — back-compat with any
+    // client that pre-dates the code-aware reauth flow.
+    const legacyBody = { error: 'unauthorized' };
+    const fetchImpl = jest.fn().mockResolvedValue(makeUpstreamResponse({
+      status: 401,
+      body: JSON.stringify(legacyBody),
+      headers: { 'content-type': 'application/json' },
+    }));
+    const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+    try {
+      const res = await fetch(`${baseUrl}/api/marketplace/items/abc`);
+      expect(res.status).toBe(401);
+      const j = await res.json();
+      expect(j).toEqual(legacyBody);
+      expect(j.code).toBeUndefined();
+    } finally { await stop(); }
+  });
+
+  test('upstream 401 on /items/:id/download is forwarded with body intact (integrity check does NOT mask auth failure)', async () => {
+    // The download path is the security-critical one: when upstream
+    // returns 401, the proxy's integrity buffering must NOT swallow
+    // the auth-error envelope and replace it with a 502. The web-UI
+    // guard relies on receiving the same { error, code } body it would
+    // on any other endpoint.
+    const upstreamBody = { error: 'Token expired', code: 'token_expired' };
+    const fetchImpl = jest.fn().mockResolvedValue(makeUpstreamResponse({
+      status: 401,
+      body: JSON.stringify(upstreamBody),
+      headers: { 'content-type': 'application/json' },
+    }));
+    const { baseUrl, stop } = await startServer(buildRouter({ fetchImpl }));
+
+    try {
+      const res = await fetch(`${baseUrl}/api/marketplace/items/abc/download`, {
+        headers: { 'Authorization': `Bearer ${SAMPLE_JWT}` },
+      });
+      // 401 (NOT 502 integrity_mismatch / upstream_unreachable).
+      expect(res.status).toBe(401);
+      const j = await res.json();
+      expect(j).toEqual(upstreamBody);
+      expect(j.code).toBe('token_expired');
+      // The integrity-verified header MUST NOT be set on an error
+      // response — would mislead the renderer into trusting an
+      // error envelope as a verified payload.
+      expect(res.headers.get('x-integrity-verified')).not.toBe('true');
+    } finally { await stop(); }
+  });
+});
+
+// ──────────────────────────────────────────────────────────────────
+// __test__ export sanity (so future refactors can't quietly drop them)
+// ──────────────────────────────────────────────────────────────────
+
+describe('exported test helpers', () => {
+  test('__test__ exposes parseContentHashHeader + verifyDownloadBytes', () => {
+    expect(__test__.parseContentHashHeader).toBe(parseContentHashHeader);
+    expect(__test__.verifyDownloadBytes).toBe(verifyDownloadBytes);
+  });
+});