@bongos/core 1.19.566 → 1.19.568

package/tests/origin_containment.mjs

@@ -0,0 +1,114 @@
+// tests/origin_containment.mjs — the downward-only containment rule (task 1003670,
+// ADR 0254): may a URL a REMOTE instance reported be published under that instance's
+// name?
+//
+// Two surfaces relay a third party's URL into an anchor on the hub — a builder's ship
+// links and a project's `hall_origin` — and until this task they answered the question
+// differently: the ship link demanded containment, the hall address demanded only that
+// the host DIFFER from the project's site. This file is the rule's own proof, so the
+// two callers cannot drift again.
+//
+// EVERY CASE HERE IS AN ATTACK OR THE SHAPE THAT MAKES ONE POSSIBLE. What is asserted
+// is what is REFUSED; the accept list is deliberately short, because a containment rule
+// that is generous is not one.
+//
+// Run:  node --test tests/origin_containment.mjs
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+// A REAL ESM import, not createRequire: knip does not trace createRequire(), and this
+// is the export's only test (learning: knip-createrequire-test-imports).
+import { urlWithinOrigin } from '../modules/platform-identity/origin-containment.js';
+
+const ORIGIN = 'https://project.example';
+
+test('a link at the reporting origin itself is kept, verbatim', () => {
+  assert.equal(urlWithinOrigin(`${ORIGIN}/builders#/task/1`, ORIGIN), `${ORIGIN}/builders#/task/1`);
+  assert.equal(urlWithinOrigin(ORIGIN, ORIGIN), ORIGIN);
+});
+
+test('a link BELOW the reporting origin is kept — the hall on a subdomain is the whole point', () => {
+  const hall = 'https://builders.project.example/';
+  assert.equal(urlWithinOrigin(hall, ORIGIN), hall);
+  assert.equal(urlWithinOrigin('https://a.b.c.project.example/x', ORIGIN), 'https://a.b.c.project.example/x',
+    'depth is not bounded — every label below the origin is still the origin\'s own');
+});
+
+test('the host comparison ignores case, and a port is not a trust boundary', () => {
+  assert.equal(urlWithinOrigin('https://BUILDERS.Project.Example/x', ORIGIN), 'https://BUILDERS.Project.Example/x');
+  assert.equal(urlWithinOrigin('https://project.example:8443/x', ORIGIN), 'https://project.example:8443/x');
+  assert.equal(urlWithinOrigin('http://project.example/x', ORIGIN), 'http://project.example/x',
+    'http is allowed — the scheme gate is about javascript:, not about TLS');
+});
+
+/* ── the refusals: each row is a way a hostile instance tries to publish a link that
+   is not its own, under a name that is ─────────────────────────────────────────── */
+
+for (const [attack, raw, origin] of [
+  // The plain one this task exists for: a remote instance advertising a hall it does
+  // not own, which the hub then renders as an <a href> under the victim's project.
+  ['an unrelated host', 'https://evil.example/phish', ORIGIN],
+  ['an unrelated host with a convincing path', 'https://evil.example/project.example/builders', ORIGIN],
+
+  // A shared multi-tenant apex, the shape origin-containment.js's header names: the
+  // neighbour is NOT the neighbour's to link, and neither is the apex above both.
+  ['a SIBLING under a shared apex', 'https://bar.pages.example/x', 'https://foo.pages.example'],
+  ['an ANCESTOR of its own host (the github.io shape)', 'https://pages.example/x', 'https://foo.pages.example'],
+  ['the bare apex of a deep origin', 'https://example/x', 'https://a.b.example'],
+
+  // Suffix matching without the dot anchor is a lookalike-domain generator: every
+  // registrable name that ENDS in the victim's name would contain it.
+  ['a lookalike domain that merely ends in the origin', 'https://notproject.example/x', ORIGIN],
+  ['a lookalike with the origin as a bare substring', 'https://project.example.evil.test/x', ORIGIN],
+
+  // The host check alone passes this: the host IS evil.example. What a human reads is
+  // the victim's domain, which is the entire trick.
+  ['credentials that read as the victim\'s domain', 'https://project.example@evil.example/x', ORIGIN],
+  ['user:password credentials on the origin itself', 'https://user:pw@project.example/x', ORIGIN],
+
+  // A relayed href is a script sink if the scheme is not constrained here.
+  ['a javascript: scheme', 'javascript:alert(1)', ORIGIN],
+  ['a data: URL', 'data:text/html,<script>alert(1)</script>', ORIGIN],
+  ['a file: URL', 'file:///etc/passwd', ORIGIN],
+  ['a protocol-relative URL', '//evil.example/x', ORIGIN],
+
+  // Not a URL, or not a string at all — a third-party JSON field is any shape.
+  ['a bare path', '/builders', ORIGIN],
+  ['an empty string', '', ORIGIN],
+  ['a number', 12345, ORIGIN],
+  ['an object', { href: `${ORIGIN}/x` }, ORIGIN],
+  ['null', null, ORIGIN],
+  ['undefined', undefined, ORIGIN],
+
+  // The ORIGIN side is stored data, not validated data. A hostless one leaves the
+  // suffix as a bare ".", which a legal trailing-dot FQDN would match.
+  ['a trailing-dot FQDN against a hostless origin', 'https://evil.example./x', 'data:text/plain,x'],
+  ['any link against a hostless origin', 'https://evil.example/x', 'file:///tmp/x'],
+  ['any link against an unparseable origin', 'https://evil.example/x', 'not-a-url'],
+  ['any link against an empty origin', 'https://evil.example/x', ''],
+  ['any link against a null origin', 'https://evil.example/x', null],
+]) {
+  test(`REFUSED: ${attack}`, () => {
+    assert.equal(urlWithinOrigin(raw, origin), null);
+  });
+}
+
+test('REFUSED: a URL over the cap — refused whole, never truncated', () => {
+  // Truncation is the tempting alternative and it is worse: a sliced URL still parses
+  // and points somewhere else, so the hub would publish a link nobody wrote.
+  const long = `${ORIGIN}/${'x'.repeat(600)}`;
+  assert.equal(urlWithinOrigin(long, ORIGIN), null, 'contained, but too long — still refused');
+  assert.equal(urlWithinOrigin(long, ORIGIN, 1000), long, 'the cap is the only thing refusing it');
+  assert.equal(urlWithinOrigin(`${ORIGIN}/x`, ORIGIN, 5), null, 'a caller may bound it tighter');
+});
+
+test('a refusal is always null — never a throw, and never a repaired URL', () => {
+  for (const raw of ['https://evil.example/x', 'javascript:alert(1)', 'http://', 7, [], true]) {
+    const out = urlWithinOrigin(raw, ORIGIN);
+    assert.equal(out, null, `${String(raw)} → null`);
+  }
+  // The kept value is the INPUT, byte for byte: normalising it here would mean the hub
+  // publishes a URL the instance never reported.
+  const odd = `${ORIGIN}/a//b?q=1#f`;
+  assert.equal(urlWithinOrigin(odd, ORIGIN), odd);
+});

package/tests/project_stats.mjs

@@ -21,7 +21,17 @@ const require = createRequire(import.meta.url);
 const stats = require('../modules/platform-identity/project-stats.js');
 
 const realFetch = globalThis.fetch;
-afterEach(() => { globalThis.fetch = realFetch; });
+// The SSRF guard's resolver. Most fixtures below dodge it with literal IPs, but the
+// hall-containment group needs real HOSTNAMES — containment is a question about
+// domain labels, and an IP origin cannot express "a subdomain of my own site". The
+// module captured `require('node:dns').promises` (the object) at load, so replacing
+// `.lookup` on it is what the guard actually calls.
+const dnsPromises = require('node:dns').promises;
+const realLookup = dnsPromises.lookup;
+function stubDns() {
+  dnsPromises.lookup = () => Promise.resolve([{ address: '93.184.216.34', family: 4 }]);
+}
+afterEach(() => { globalThis.fetch = realFetch; dnsPromises.lookup = realLookup; });
 beforeEach(() => { stats._reset(); });
 
 function json(body) {
@@ -359,28 +369,86 @@ test('the shipped feed is asked for the window explicitly', async () => {
   assert.ok(urls.includes('https://8.8.8.8/api/bongos'), 'the discovery index answers the hall address');
 });
 
-test('hall_origin is the discovery index\'s hall only where it is a different host from the site', async () => {
-  stub({
-    'https://1.1.1.1': { leaderboard: [], enabled: {}, index: { hall: 'https://builders.example.com' } },
-    'https://8.8.8.8': { leaderboard: [], enabled: {}, index: { hall: 'https://8.8.8.8' } },      // single host
-    'https://9.9.9.9': { leaderboard: [], enabled: {}, index: { hall: 'javascript:alert(1)' } },
-    'https://4.4.4.4': { leaderboard: [], enabled: {} },                                           // no index (older core)
-  });
-  const out = await stats.getProjectStats(['https://1.1.1.1', 'https://8.8.8.8', 'https://9.9.9.9', 'https://4.4.4.4']);
-  assert.equal(out['https://1.1.1.1'].hall_origin, 'https://builders.example.com');
-  assert.equal(out['https://8.8.8.8'].hall_origin, null, 'a hall at <site>/builders is the site\'s own door');
-  assert.equal(out['https://9.9.9.9'].hall_origin, null);
+/* ── hall_origin: CONTAINMENT first, the door test second ───────────────────────
+   This is the one value in this file that becomes an <a href> on the hub rather
+   than an <img src>, and it arrives from a REMOTE instance's own discovery index.
+   It used to be checked only for DIFFERING from the project's site host — which is
+   containment inverted: it admitted every host on the internet except the one that
+   was certainly safe. Task 1003670 / ADR 0254 put it on the same downward-only rule
+   a pushed ship link obeys (origin-containment.js, whose own attack matrix is
+   tests/origin_containment.mjs). What is asserted here is the WIRING: that a sweep
+   through getProjectStats really refuses these.
+
+   Hostname fixtures, not the file's usual literal IPs — see stubDns() above. ── */
+
+// each row: [why, origin, the hall the remote advertises, what the hub may publish]
+const HALL_CASES = [
+  ['a hall on a subdomain of the project\'s own origin is the legitimate shape',
+    'https://good.example', 'https://builders.good.example', 'https://builders.good.example'],
+  ['another PORT on the same host is a real second door — a port is not a trust boundary',
+    'https://port.example', 'https://port.example:8443', 'https://port.example:8443'],
+  ['a hall AT the site host is the site\'s own door, not a second one',
+    'https://solo.example', 'https://solo.example', null],
+  // THE ATTACK. Under ADR 0252's auto-appear anyone who points a domain at the hub
+  // can report this, and the old rule published it BECAUSE it differed.
+  ['an unrelated host is a phishing hop, and differing is exactly what used to admit it',
+    'https://victim.example', 'https://evil.example/builders', null],
+  ['a SIBLING under a shared apex belongs to the neighbour',
+    'https://foo.pages.example', 'https://bar.pages.example', null],
+  ['an ANCESTOR of the project\'s own host is the github.io shape — never upward',
+    'https://foo.pages.example', 'https://pages.example', null],
+  ['a lookalike domain that merely ENDS in the origin (the dot anchor)',
+    'https://look.example', 'https://notlook.example', null],
+  ['embedded credentials that read as the project\'s own domain',
+    'https://creds.example', 'https://creds.example@evil.example/builders', null],
+  ['a non-http scheme never becomes an href',
+    'https://scheme.example', 'javascript:alert(1)', null],
+  ['a hall over the URL cap is refused whole, never truncated into a different address',
+    'https://long.example', `https://a.long.example/${'x'.repeat(400)}`, null],
+  ['a hall the project does not name',
+    'https://quiet.example', undefined, null],
+];
+
+test('hall_origin publishes a hall only at or BELOW the project\'s own origin, and only where it is a different door', async () => {
+  stubDns();
+  const fixtures = {};
+  for (const [, origin, hall] of HALL_CASES) {
+    fixtures[origin] = { leaderboard: [], enabled: {}, index: hall === undefined ? {} : { hall } };
+  }
+  stub(fixtures);
+  const out = await stats.getProjectStats(HALL_CASES.map(([, origin]) => origin));
+  for (const [why, origin, , expected] of HALL_CASES) {
+    assert.equal(out[origin].hall_origin, expected, why);
+  }
+});
+
+test('a project with no discovery index at all (an older core) reports no hall', async () => {
+  stub({ 'https://4.4.4.4': { leaderboard: [], enabled: {} } });
+  const out = await stats.getProjectStats(['https://4.4.4.4']);
   assert.equal(out['https://4.4.4.4'].hall_origin, null);
 });
 
+test('containment is read from the ONE shared rule, not re-implemented here', async () => {
+  // The defect this replaced was a second, weaker answer to a question the corpus had
+  // already answered one field over. A local re-implementation would drift again.
+  const src = await import('node:fs').then((fs) =>
+    fs.readFileSync(new URL('../modules/platform-identity/project-stats.js', import.meta.url), 'utf8'));
+  assert.match(src, /require\('\.\/origin-containment'\)/, 'the rule is required, not copied');
+  const fn = (src.match(/function hallOrigin\([\s\S]*?\n\}/) || [''])[0];
+  assert.match(fn, /urlWithinOrigin\(index\?\.hall, origin, URL_MAX\)/, 'the hall is contained before anything else looks at it');
+  assert.doesNotMatch(fn, /httpUrl\(/, 'httpUrl only scheme-checks and TRUNCATES — it is not a containment rule');
+});
+
 test('a dead shipped feed leaves the other quarters standing', async () => {
-  stub({ 'https://8.8.8.8': { leaderboard: [{ github_login: 'a' }], enabled: { game: true }, index: { hall: 'https://h.example.com' } } });
+  // the hall is on this project's OWN host (another port) — anything else is refused
+  // by containment now, which would make this test prove the wrong thing
+  stub({ 'https://8.8.8.8': { leaderboard: [{ github_login: 'a' }], enabled: { game: true }, index: { hall: 'https://8.8.8.8:8443' } } });
   const out = await stats.getProjectStats(['https://8.8.8.8']);
   assert.equal(out['https://8.8.8.8'].shipped_30d, null, 'the dead quarter is unknown');
   assert.equal(out['https://8.8.8.8'].shipped_30d_capped, null);
   assert.equal(out['https://8.8.8.8'].builders, 1);
   assert.deepEqual(out['https://8.8.8.8'].tags, ['game']);
-  assert.equal(out['https://8.8.8.8'].hall_origin, 'https://h.example.com');
+  assert.equal(out['https://8.8.8.8'].hall_origin, 'https://8.8.8.8:8443');
 });
 
 test('the origin\'s host is resolved once per sweep, not once per feed', async () => {

package/tests/visible_projects_feed.mjs

@@ -16,6 +16,13 @@
 //   3. WHAT A BLACK HOLE MAY SAY. Stealth exposes EXISTENCE, never IDENTITY (D2a), and
 //      the redaction is at the boundary because the orbs page is a static site outside
 //      this repo and could not be trusted to redact even in principle.
+//   4. IN WHAT ORDER, and on what page (task 1003561, which absorbed task 1003560; ADR
+//      0255). The ORDER BY is a covert column, and it was leaking one: sorting by
+//      `updated_at` — which this projection deliberately withholds — MOVED a black hole
+//      whenever its hidden project was touched, handing an observer the stable,
+//      activity-tracking handle STEALTH_ANONYMOUS_KEEPS exists to refuse. A row is now
+//      ordered only by what it publishes, anonymous rows are one keyed-permuted trailing
+//      block, and the 500-row cap became a page window instead of a silent truncation.
 //
 // The stealth assertions are the security spec: they assert ABSENT FIELDS, not absent
 // pixels, which is what R10 (task 1002329) then demonstrates live.
@@ -194,20 +201,147 @@ test('featuring no longer GATES presence — it only ranks among projects alread
   const sql = pool.calls[0].text;
   const where = (sql.match(/WHERE([\s\S]*?)ORDER BY/i) || [, ''])[1];
   assert.doesNotMatch(where, /featured/, 'featured must not appear in the predicate at all');
-  assert.match(sql, /ORDER BY featured DESC/, 'it keeps the job D3 leaves it: ranking');
+  const order = (sql.match(/ORDER BY([\s\S]*?)LIMIT/i) || [, ''])[1];
+  assert.match(order, /AND featured\) DESC/,
+    'it keeps the job D3 leaves it: ranking — now guarded, so it ranks only rows that publish a name');
 });
 
-test('the public feed is CAPPED — the swap to self-service removed the human bound on its size', async () => {
+test('the cap is now a PAGE WINDOW — bound as parameters and clamped to the fan-out ceiling', async () => {
   // Until R06 the listing was bounded by an Archon choosing to feature a project. Making
   // it `publishable` replaced that bound with self-service, on a route that is public,
-  // CORS-open, unauthenticated AND fans out one outbound stats fetch per row. The cap is
-  // the cheap half of that trade; pagination is its own task.
+  // CORS-open, unauthenticated AND fans out up to four outbound stats fetches per cold
+  // row. Task 1002325 answered with a hard LIMIT 500 — the cheap half. This is the honest
+  // half (task 1003560, merged into 1003561): the same 500 still bounds one request's
+  // fan-out, but a caller can now reach past it instead of being truncated in silence.
+  const pool = mockPool([{ rows: [] }]);
+  await pi.listPublicProjects({ pool, limit: 10000, offset: 25 });
+  const { text, params } = pool.calls[0];
+  assert.match(text, /LIMIT \$2::int OFFSET \$3::int/,
+    'the window is BOUND, never interpolated — it is the first caller-supplied value this SQL has ever carried');
+  assert.equal(params[1], feed.PUBLIC_FEED_MAX_PAGE_SIZE,
+    'a caller cannot ask past the ceiling, so no request can aim more fan-out than one could before');
+  assert.equal(params[2], 25);
+});
+
+test('no window at all means the OLD hard cap, so every pre-paging consumer is unchanged', async () => {
+  // The compatibility guarantee, asserted rather than trusted: one consumer of this feed
+  // is a static orbs site in ANOTHER REPO that this commit cannot update. A default page
+  // smaller than the old LIMIT would have silently shrunk somebody else's map.
   const pool = mockPool([{ rows: [] }]);
   await pi.listPublicProjects({ pool });
-  assert.match(pool.calls[0].text, new RegExp(`LIMIT ${feed.PUBLIC_FEED_MAX_PROJECTS}\\b`));
-  assert.equal(Number.isInteger(feed.PUBLIC_FEED_MAX_PROJECTS), true,
-    'the cap is interpolated into SQL, so it must be a literal integer and never a caller value');
-  assert.ok(feed.PUBLIC_FEED_MAX_PROJECTS > 0);
+  assert.deepEqual(pool.calls[0].params.slice(1), [feed.PUBLIC_FEED_MAX_PAGE_SIZE, 0]);
+  assert.equal(feed.PUBLIC_FEED_MAX_PAGE_SIZE, 500, 'the number the feed was capped at before it could page');
+});
+
+test('a nonsense window is CLAMPED, never rejected and never unbounded', async () => {
+  // Clamped in listPublicProjects as well as at the route: this is a module-public
+  // function and the ceiling is a fan-out bound, so it may not depend on every future
+  // caller remembering to pass one.
+  const pool = mockPool([{ rows: [] }, { rows: [] }]);
+  await pi.listPublicProjects({ pool, limit: -1, offset: -50 });
+  assert.deepEqual(pool.calls[0].params.slice(1), [feed.PUBLIC_FEED_MAX_PAGE_SIZE, 0]);
+  await pi.listPublicProjects({ pool, limit: 'all', offset: 'next' });
+  assert.deepEqual(pool.calls[1].params.slice(1), [feed.PUBLIC_FEED_MAX_PAGE_SIZE, 0]);
+});
+
+// ── the ORDER BY is part of the payload (task 1003561, ADR 0255) ─────────────
+
+// The ORDER BY's terms, with the identified-state predicate masked so a naive comma
+// split survives the comma inside its IN-list.
+function orderTerms(sql) {
+  const clause = (sql.match(/ORDER BY([\s\S]*?)LIMIT/i) || [, ''])[1];
+  return clause.split(feed.IDENTIFIED_SQL).join('<identified>')
+    .split(',').map((t) => t.trim().replace(/\s+/g, ' ')).filter(Boolean);
+}
+
+async function feedSql(opts = {}) {
+  const pool = mockPool([{ rows: [] }]);
+  await pi.listPublicProjects({ pool, ...opts });
+  return pool.calls[0];
+}
+
+test('updated_at is gone from the query ENTIRELY — it may no longer even sort', async () => {
+  // THE bug (task 1003561). A public list's ORDER BY is a covert column: sorting by a
+  // value the projection withholds publishes it anyway, one comparison at a time. For a
+  // black hole that meant its position moved the moment its hidden project was touched.
+  const { text } = await feedSql();
+  assert.doesNotMatch(text, /updated_at/,
+    'not in the projection, and since task 1003561 not in the ORDER BY either');
+});
+
+test('anonymous rows are collated into ONE TRAILING BLOCK, never interleaved with named ones', async () => {
+  // The separation is what makes position meaningless: a black hole neighbours no named
+  // row, so it can no longer be bracketed between two rows whose own order is visible.
+  const terms = orderTerms((await feedSql()).text);
+  assert.equal(terms[0], '<identified> DESC',
+    'the FIRST sort term partitions the two blocks, so no later term ever compares across them');
+});
+
+test('no identified sort key is ever applied to an anonymous row', async () => {
+  // Blanking terms 2-4 is the whole trick. Without it, the trailing block would simply be
+  // re-sorted by featured, then created_at, then origin — none of which a black hole
+  // publishes, and created_at in particular would narrow WHICH project it is to anyone
+  // who watched the catalog fill up.
+  const terms = orderTerms((await feedSql()).text);
+  for (const [i, key] of [[1, 'featured'], [2, 'created_at'], [3, 'origin']]) {
+    assert.ok(terms[i].includes(key), `term ${i} ranks identified rows by ${key}`);
+    assert.ok(terms[i].includes('<identified>'),
+      `and it is guarded, so ${key} never orders an anonymous row`);
+  }
+  assert.ok(terms[3].includes('ELSE md5('),
+    'the anonymous block gets a permutation where the identified block gets its public keys');
+  assert.equal(terms.length, 4, 'and there is no fifth, unguarded term');
+});
+
+test('the anonymous permutation reads a BOUND salt — the key never enters the SQL text', async () => {
+  const { text, params } = await feedSql({ now: 0 });
+  assert.match(text, /md5\(origin \|\| \$1::text\)/, 'the hash reads its salt from $1');
+  assert.equal(params[0], feed.anonymousOrderSalt(0));
+  assert.ok(!text.includes(params[0]), 'and the secret is never interpolated into the query');
+});
+
+test('the permutation salt is KEYED and re-deals on an epoch — it is not a clock reading', () => {
+  // Two properties, and both are load-bearing. SECRET: origins are guessable (they are
+  // domain names), so a salt an observer could predict would let them hash their
+  // candidates, match the ranks and de-anonymise the whole block in one pass. ROTATING:
+  // a permanently stable order would make POSITION the durable per-project key that
+  // STEALTH_ANONYMOUS_KEEPS refuses to put on the wire.
+  const epoch = feed.ANONYMOUS_ORDER_EPOCH_MS;
+  const salt = feed.anonymousOrderSalt(1000);
+  assert.equal(feed.anonymousOrderSalt(epoch - 1), salt,
+    'stable within one period, so the pages of a single listing agree with each other');
+  assert.notEqual(feed.anonymousOrderSalt(epoch + 1), salt,
+    're-dealt across periods, so today\'s rank is not tomorrow\'s black hole');
+  const [key, period] = salt.split(':');
+  assert.equal(period, '0');
+  assert.match(key, /^[0-9a-f]{32}$/, 'a random per-process key — not a timestamp, not a constant');
+});
+
+test('SQL and feedShapeFor cannot disagree about who is anonymous — both read ORB_BY_STATE', () => {
+  // The two halves of one decision, written in two languages. A disagreement would not be
+  // cosmetic: SQL calling a state identified while feedShapeFor redacts it would POSITION
+  // the row by a created_at that its own wire row does not carry — exactly the leak this
+  // ordering closes, reopened one enum value later.
+  for (const state of feed.IDENTIFIED_STATES) {
+    assert.notEqual(feed.orbForState(state), 'black-hole', `${state} sorts identified, so it must render identified`);
+    assert.equal(feed.feedShapeFor({ ...PUBLIC_ROW, visibility: state }).name, 'Mercury');
+    assert.ok(feed.IDENTIFIED_SQL.includes(`'${state}'`), 'and the SQL names it too');
+  }
+  assert.deepEqual([...feed.IDENTIFIED_STATES].sort(), ['private', 'public']);
+  assert.ok(!feed.IDENTIFIED_STATES.includes(feed.FALLBACK_PROJECT_STATE),
+    'the anonymous fallback is never in the identified set');
+});
+
+test('the identified set is an ALLOW-list, so an unknown state SORTS anonymous too', () => {
+  // The same fail-closed direction orbStateOf() already took for rendering. A fourth enum
+  // value added upstream and forgotten here draws as a black hole AND sorts into the
+  // anonymous block; a deny-list would have drawn it anonymous but sorted it by its
+  // created_at, which is the worst of both.
+  assert.match(feed.IDENTIFIED_SQL, /^\(visibility IN \(/,
+    'an allow-list: identified by naming, never identified by omission');
+  assert.doesNotMatch(feed.IDENTIFIED_SQL, /NOT IN/);
+  assert.ok(!feed.IDENTIFIED_SQL.includes("'members-only'"));
+  assert.equal(feed.orbForState('members-only'), 'black-hole');
 });
 
 test('listPublicProjects projects `visibility`, the column the orb is derived from', async () => {
@@ -229,7 +363,8 @@ test('listPublicProjects stays a PUBLIC projection — no owner, no status, no b
   assert.ok(sel.trim(), 'the projection is an explicit SELECT list');
   assert.doesNotMatch(sel, /\*/, 'no star projection on a public route');
   assert.doesNotMatch(sel, /owner_github_id/, 'public projection must not leak owner id');
-  assert.doesNotMatch(sel, /updated_at/, 'curation noise — it may sort, it may never project');
+  assert.doesNotMatch(sel, /updated_at/,
+    'curation noise: it never projected, and since task 1003561 it does not sort either');
   assert.doesNotMatch(sel, /\bdescription\b/,
     'description is the publish BAR, not a card field — it is spent in the predicate');
   assert.match(sel, /created_at/, 'the LISTED date stays public');
@@ -241,16 +376,17 @@ test('listPublicProjects stays a PUBLIC projection — no owner, no status, no b
 // The real router, driven with a fake req/res. `pi.listPublicProjects` and the stats
 // enrichment are stubbed so the test needs neither Postgres nor the network — what is
 // under test is the ROUTE's composition, not either dependency.
-async function callFeaturedFeed(rows) {
+async function callFeaturedFeed(rows, query) {
   const router = projectsRoutes();
   const layer = router.stack.find((l) => l.route && l.route.path === '/projects/featured'
     && l.route.methods.get);
   assert.ok(layer, 'GET /projects/featured must still be a route on this router');
 
   const askedFor = [];
+  const listArgs = [];
   const savedList = pi.listPublicProjects;
   const savedStats = projectStats.getProjectStats;
-  pi.listPublicProjects = async () => rows;
+  pi.listPublicProjects = async (args) => { listArgs.push(args || {}); return rows; };
   projectStats.getProjectStats = async (origins) => { askedFor.push(...origins); return {}; };
   try {
     let body = null;
@@ -264,13 +400,13 @@ async function callFeaturedFeed(rows) {
     // would exercise the ceiling and never reach the route — and, worse, would keep
     // passing as a silent no-op if the handler were ever removed. A fresh req per call
     // keeps each test's reads out of the previous one's budget.
-    const req = { ip: `198.51.100.${Math.floor(Math.random() * 200) + 1}` };
+    const req = { ip: `198.51.100.${Math.floor(Math.random() * 200) + 1}`, query: query || {} };
     for (const entry of layer.route.stack) {
       let advanced = false;
       await entry.handle(req, res, () => { advanced = true; });
       if (!advanced) break;   // something short-circuited (a refusal), or it was the handler
     }
-    return { body, askedFor };
+    return { body, askedFor, listArgs };
   } finally {
     pi.listPublicProjects = savedList;
     projectStats.getProjectStats = savedStats;
@@ -329,3 +465,38 @@ test('dark matter never reaches the route at all — the exclusion is in SQL', a
   const fn = (src.match(/async function listPublicProjects[\s\S]*?\n\}/) || [''])[0];
   assert.ok(fn.includes('publishableSql()'), 'the gate is applied in the query, not after it');
 });
+
+// ── the route's half of the page window (task 1003560 → 1003561) ─────────────
+
+test('the route pages with ?limit=&offset= and reports back the window it used', async () => {
+  // ADR 0119's contract, which this feed was the last public list to hold out on.
+  const { body, listArgs } = await callFeaturedFeed([{ ...PUBLIC_ROW }], { limit: '2', offset: '4' });
+  assert.equal(listArgs[0].limit, 2);
+  assert.equal(listArgs[0].offset, 4);
+  assert.deepEqual(body.page, { limit: 2, offset: 4 });
+  assert.ok(Array.isArray(body.projects),
+    '`projects` keeps its name and its place — every consumer destructures it, so the wire is additive');
+});
+
+test('an unparamed read still asks for the whole ceiling — the other-repo orbs site is unchanged', async () => {
+  const { body, listArgs } = await callFeaturedFeed([{ ...PUBLIC_ROW }]);
+  assert.equal(listArgs[0].limit, pi.PUBLIC_FEED_MAX_PAGE_SIZE);
+  assert.equal(listArgs[0].offset, 0);
+  assert.deepEqual(body.page, { limit: pi.PUBLIC_FEED_MAX_PAGE_SIZE, offset: 0 });
+});
+
+test('?limit= can only SHRINK a page, so paging cannot aim more fan-out than one request already could', async () => {
+  // The constraint that makes paging safe on a public, CORS-open, unauthenticated route
+  // whose every cold row costs four outbound fetches at somebody else's server.
+  const { listArgs } = await callFeaturedFeed([], { limit: '99999' });
+  assert.equal(listArgs[0].limit, pi.PUBLIC_FEED_MAX_PAGE_SIZE);
+});
+
+test('no cursor: the page token is an offset, which encodes nothing about any row', async () => {
+  // Deliberate, and a security property as much as a style one. An opaque cursor over this
+  // feed would have to encode a sort position, and the obvious encoding — the last row's
+  // timestamp — is the very side-channel the ORDER BY above was rewritten to close.
+  const { body } = await callFeaturedFeed([{ ...PUBLIC_ROW }], { offset: '3' });
+  assert.deepEqual(Object.keys(body.page).sort(), ['limit', 'offset']);
+  assert.equal(body.page.offset, 3);
+});