onbuzz 4.9.13 → 4.10.0

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

@@ -1,629 +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);
-  });
-});
+/**
+ * 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 } 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);
+  });
+});