@bongos/core 1.19.566 → 1.19.568

package/modules/platform-identity/origin-containment.js

@@ -0,0 +1,77 @@
+// modules/platform-identity/origin-containment.js — THE rule deciding whether a URL a
+// REMOTE instance handed us may be published under that instance's name: it has to point
+// AT OR BELOW the origin that reported it. One question, one file, so the two surfaces
+// that ask it cannot answer it differently (the publish-gate.js precedent).
+//
+// TWO CALLERS, which is why this stopped being a private helper (task 1003670, ADR 0254):
+//   • a pushed ship link on a builder's public portfolio — platform-identity.js
+//     `sanitizeRecentShips`, bounded by the AUTHENTICATED client's registered origin
+//   • `hall_origin` on the public projects feed — project-stats.js `hallOrigin`, bounded
+//     by the project's own catalog origin
+// The second arrived WITHOUT the rule: it checked only that the advertised hall host
+// DIFFERED from the project's site host, which is the exact opposite of containment — it
+// admits every host on the internet except the one that is certainly safe. A remote
+// instance answering `GET /api/bongos` with `hall: "https://evil.example"` had that link
+// relayed into an `<a href>` on the hub, under the victim project's name.
+//
+// WHY IT GOT URGENT. [ADR 0252](../../docs/adr/0252-the-self-hosted-visibility-report-is-a-pull-and-auto-appear-buys-a-retraction-lever.md)
+// §5 named this gap in the same breath as deciding that a self-hosted project
+// AUTO-APPEARS on the map. Under control-plane provisioning the origin set was bounded by
+// whom the operator had provisioned; auto-appear replaces that bound with "whoever points
+// a domain at the hub", which turns a curated-origin risk into a phishing hop anyone can
+// mint. Containment is what makes the relayed link mean something again: a hall link on
+// the hub can only ever address the project it is filed under.
+//
+// DOWNWARD ONLY, deliberately. The mirror rule ("the link host is an ANCESTOR of the
+// reporting origin") looks symmetric and is not: on a shared multi-tenant apex it would
+// let an instance registered at foo.github.io publish links on bare github.io, which it
+// does not control. Nothing needs the upward direction — a reporting origin is the
+// instance's own public origin — so it is not offered.
+//
+// WHY ITS OWN FILE. The rule could not simply be shared where it sat: `platform-identity.js`
+// is AT its file-size ratchet (scripts/gds/fitness-ratchets.js, 1500 lines, no headroom)
+// and `project-stats.js` is a different file besides — the account-visibility.js /
+// publish-gate.js / projects-feed.js precedent, taken here for the same reason. It is
+// deliberately NOT re-exported from `platform-identity.js`: both callers require it
+// directly, so there is exactly one name for one answer.
+'use strict';
+
+// A relayed URL is REFUSED at the cap, never truncated. Slicing a URL changes where it
+// points, and a shortened one that still parses is a worse answer than no link at all —
+// which is why this is a bound and not a `slice()` (contrast `project-stats.js:httpUrl`,
+// whose cap is a display bound on an <img src>, not a containment decision).
+const MAX_CONTAINED_URL_LENGTH = 500;
+
+// urlWithinOrigin — `raw` when it is an http(s) URL at or below `origin`'s host, else
+// null. Every refusal is a null: never a throw, never a repaired value. The callers
+// publish the link exactly as reported, or they publish nothing.
+//
+// Each check earns its place, and each is a real reported attack shape:
+//   • http(s) only — a `javascript:` href relayed into an anchor is stored XSS, and the
+//     hub's clients scheme-check again only because defence in depth is cheap.
+//   • no username/password — `https://cloudbongos.com@evil.example/x` reads as the
+//     victim's domain to a human and resolves to the attacker's; the host check alone
+//     passes it, because the host IS evil.example.
+//   • host equals the registered host, or is a DOT-ANCHORED suffix of it. The dot is
+//     load-bearing: without it `notcloudbongos.com` ends with `cloudbongos.com`, and
+//     every lookalike domain contains the domain it imitates.
+//
+// `max` is a parameter because the two callers carry different display bounds; the
+// default is the ship-link cap this rule was lifted from, so that call site is unchanged.
+function urlWithinOrigin(raw, origin, max = MAX_CONTAINED_URL_LENGTH) {
+  if (typeof raw !== 'string' || !raw || raw.length > max) return null;
+  let u, o;
+  try { u = new URL(raw); o = new URL(String(origin || '')); } catch { return null; }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return null;
+  if (u.username || u.password) return null;
+  const host = u.hostname.toLowerCase(), registered = o.hostname.toLowerCase();
+  // An origin with no host at all (`file:`, `data:` — a stored value is not a validated
+  // one) leaves `registered` empty, and `.` is then the whole suffix: a trailing-dot
+  // FQDN like `evil.example.` is legal in a URL and WOULD match it. Refuse first, so a
+  // hostless origin can never be the thing that authorises a link.
+  if (!registered) return null;
+  if (host !== registered && !host.endsWith(`.${registered}`)) return null;
+  return raw;
+}
+
+module.exports = { urlWithinOrigin };

package/modules/platform-identity/platform-identity.js

@@ -19,6 +19,11 @@ const api = require('../../src/module-api');
 // re-derives one (see account-visibility.js).
 const visibility = require('./account-visibility');
 const terms = require('./terms-acceptance');
+// THE downward-only containment rule for a URL a remote instance reported (task
+// 1003670, ADR 0254). Lifted out of this file so the projects feed's `hall_origin`
+// reads the SAME rule as a ship link instead of the "different host" check it had —
+// see origin-containment.js for why it is downward only and why it lives there.
+const { urlWithinOrigin } = require('./origin-containment');
 
 const { pool: defaultPool } = api;
 const { ACCOUNT_VISIBILITY, accountVisibleSql, rollupVisibleSql, isRollupVisible, scoutingListableSql } = visibility;
@@ -317,7 +322,7 @@ const {
 // D1/D2a/D3; R06, task 1002325). Its own file for the publish-gate.js reason: this
 // file is at the size ratchet. Re-exported below, so the surface is unchanged.
 const {
-  ORB_BY_STATE, orbForState, isStealthProject, feedShapeFor, listPublicProjects,
+  ORB_BY_STATE, orbForState, isStealthProject, feedShapeFor, listPublicProjects, PUBLIC_FEED_MAX_PAGE_SIZE,
 } = require('./projects-feed');
 
 // Upsert a catalog row (keyed by origin). Called when a client registers (so every
@@ -614,37 +619,12 @@ const MAX_DISCIPLINE_LENGTH = 32;
 // buggy or hostile.
 const MAX_RECENT_SHIPS = 3;
 const MAX_SHIP_TITLE_LENGTH = 200;
-const MAX_SHIP_URL_LENGTH = 500;
 // How far into a pushed array the hub will even LOOK. Validating first and
 // capping second is what stops a few malformed entries from crowding the good
 // ones out of the three slots; bounding the scan is what stops an unbounded
 // array from buying unbounded work with one request.
 const MAX_RECENT_SHIPS_SCANNED = 20;
 
-// May this ship link be stored? A ship link is the ONLY free-text URL on a public
-// builder portfolio, which makes it the one place a client-secret holder could
-// plant a phishing hop under someone else's name. So it must point AT OR BELOW
-// the instance that reported it: the client's own REGISTERED origin host, or a
-// subdomain of it (an instance's hall may live at builders.<domain> while its
-// registered origin is <domain>). Anything else — another site, a non-http
-// scheme, embedded credentials — stores no link rather than a wrong one.
-//
-// DOWNWARD ONLY, deliberately. The mirror rule ("the link host is an ANCESTOR of
-// the registered origin") looks symmetric and is not: on a shared multi-tenant
-// apex it would let a client registered at foo.github.io publish links on bare
-// github.io, which it does not control. Nothing needs the upward direction — a
-// registered origin is the instance's own public origin — so it is not offered.
-function shipUrlWithinClientOrigin(raw, clientOrigin) {
-  if (typeof raw !== 'string' || !raw || raw.length > MAX_SHIP_URL_LENGTH) return null;
-  let u, o;
-  try { u = new URL(raw); o = new URL(String(clientOrigin || '')); } catch { return null; }
-  if (u.protocol !== 'http:' && u.protocol !== 'https:') return null;
-  if (u.username || u.password) return null;
-  const host = u.hostname.toLowerCase(), registered = o.hostname.toLowerCase();
-  if (host !== registered && !host.endsWith(`.${registered}`)) return null;
-  return raw;
-}
-
 // Shape and bound the pushed recent_ships[] before it is stored (the
 // upsertActivity rank/disciplines precedent, ADR 0171 D7 — validation lives next
 // to the data where no route can forget it). Returns AT MOST MAX_RECENT_SHIPS
@@ -652,6 +632,15 @@ function shipUrlWithinClientOrigin(raw, clientOrigin) {
 // title is dropped entirely rather than stored half-empty, and a bad date or an
 // off-origin link becomes null on an otherwise good row. Always an array, never
 // null — every reader gets a list without a coalesce.
+//
+// THE LINK IS THE DANGEROUS FIELD. A ship link is the only free-text URL on a public
+// builder portfolio, so it is the one place a client-secret holder could plant a
+// phishing hop under someone else's name. `urlWithinOrigin` is what stops that — it
+// keeps a link only where it points AT OR BELOW the reporting client's registered
+// origin (its own host, or a subdomain: an instance's hall may live at
+// builders.<domain> while its registered origin is <domain>). The rule now lives in
+// origin-containment.js because the projects feed's `hall_origin` needs the identical
+// answer and used to give a different one (task 1003670, ADR 0254).
 function sanitizeRecentShips(raw, clientOrigin) {
   return (Array.isArray(raw) ? raw : [])
     .slice(0, MAX_RECENT_SHIPS_SCANNED)
@@ -663,7 +652,7 @@ function sanitizeRecentShips(raw, clientOrigin) {
         id: Number.isSafeInteger(id) && id > 0 ? id : null,
         title: typeof s.title === 'string' && s.title.trim() ? s.title.slice(0, MAX_SHIP_TITLE_LENGTH) : null,
         shipped_at: Number.isFinite(at) ? new Date(at).toISOString() : null,
-        url: shipUrlWithinClientOrigin(s.url, clientOrigin),
+        url: urlWithinOrigin(s.url, clientOrigin),
       };
     })
     .filter((s) => s.id !== null && s.title !== null)
@@ -674,7 +663,7 @@ function sanitizeRecentShips(raw, clientOrigin) {
 // Descriptive analytics — never authority. Refreshes last_active on each report.
 // `clientOrigin` is the AUTHENTICATED client's registered origin (never a
 // caller-named one) and exists only to bound the ship links — see
-// shipUrlWithinClientOrigin.
+// origin-containment.js:urlWithinOrigin.
 async function upsertActivity({ clientId, githubId, credits = 0, tasksShipped = 0, karma = 0, rank = null, disciplines = [], recentShips = [], clientOrigin = null }, { pool = defaultPool } = {}) {
   // api.LIVE_RANK_LADDER is a published doorway export (src/module-api.js, a
   // lazy getter over db-kernel's canonical four-rank ladder).
@@ -1437,6 +1426,7 @@ module.exports = {
   PROJECT_SHAPES,
   getProject,
   listPublicProjects,
+  PUBLIC_FEED_MAX_PAGE_SIZE,
   listAllProjects,
   setProjectFeatured,
   ORB_BY_STATE,

package/modules/platform-identity/project-stats.js

@@ -30,6 +30,12 @@ const fs = require('node:fs');
 const path = require('node:path');
 const dns = require('node:dns').promises;
 const net = require('node:net');
+// THE downward-only containment rule for a URL a remote instance reported (task
+// 1003670, ADR 0254). `hall_origin` is the only value in this file that becomes an
+// `<a href>` on the hub rather than an `<img src>`, so it is the only one that has to
+// prove it belongs to the project it is filed under; the ship-link path in
+// platform-identity.js reads the identical rule from the identical place.
+const { urlWithinOrigin } = require('./origin-containment');
 
 const TTL_MS = 10 * 60 * 1000;   // owner's choice, 2026-08-13
 const FETCH_TIMEOUT_MS = 2500;   // per request
@@ -209,8 +215,34 @@ function shippedStats(body) {
 // <site>/builders, where the site's own door already leads) and null when the
 // project does not say. Task 1003257, owner decision (a): a door only where it
 // opens somewhere else.
+//
+// TWO TESTS, and the first one is the security one (task 1003670, ADR 0254). This
+// value comes out of a REMOTE instance's own discovery index and the hub relays it
+// into an `<a href>` under that project's name, so it must be CONTAINED — at or
+// below the project's own origin — before it may differ from anything. The check
+// used to be "differs from the site host" alone, which is containment inverted: it
+// admitted every host on the internet except the one that was certainly safe, so a
+// hostile or compromised instance could publish `hall: "https://evil.example"` and
+// have the hub link it. [ADR 0252](../../docs/adr/0252-the-self-hosted-visibility-report-is-a-pull-and-auto-appear-buys-a-retraction-lever.md)
+// §5 named the gap when it decided self-hosted projects AUTO-APPEAR: the origin set
+// stopped being bounded by whom the operator provisioned.
+//
+// Containment first (`urlWithinOrigin` — the SAME rule a pushed ship link obeys,
+// http(s)-only, no embedded credentials, dot-anchored suffix, refused rather than
+// truncated at the cap), and only then the door test. The door test still compares
+// `.host` WITH the port, because a hall on another port of the same machine really
+// does open somewhere else; containment compares hostnames, because a port is not a
+// trust boundary. Net effect: a hall link survives only as a strict SUBDOMAIN (or
+// another port) of the project's own origin.
+//
+// The cost, stated so it is not mistaken for a bug: a project whose hall is a
+// SIBLING of its site (site www.example.com, hall builders.example.com) loses the
+// glyph. The hall is still reachable; the hub just stops vouching for the address.
+// That is the corpus's standing asymmetry — narrowing is free, widening is what
+// costs — and the upward rule that would admit it is the one origin-containment.js
+// refuses to offer, because on a shared apex it hands away every neighbour.
 function hallOrigin(index, origin) {
-  const hall = httpUrl(index?.hall);
+  const hall = urlWithinOrigin(index?.hall, origin, URL_MAX);
   if (!hall) return null;
   try {
     return new URL(hall).host.toLowerCase() === siteUrl(origin).host.toLowerCase() ? null : hall;

package/modules/platform-identity/projects-feed.js

@@ -3,7 +3,7 @@
 // The in-repo lever the orbs page reads. The publish-gate.js precedent — one question,
 // one file, so no two surfaces can answer it differently.
 //
-// THREE ANSWERS, and they belong together because each is only safe given the others:
+// FOUR ANSWERS, and they belong together because each is only safe given the others:
 //
 //   • WHO — `listPublicProjects`. A project is on the map iff `status = 'active' AND
 //     publishable`, the derived identity gate, taken from publishableSql() so this feed
@@ -27,6 +27,13 @@
 //     project to anyone who opens the network tab — and that page is a static site
 //     outside this repo, so we could not enforce it there even in principle.
 //
+//   • IN WHAT ORDER — the ORDER BY, which is a covert answer and was leaking one until
+//     task 1003561: the feed sorted by `updated_at`, a column this projection
+//     deliberately withholds, so a black hole visibly MOVED whenever its hidden project
+//     was touched. A row is now ordered only by what it publishes, and a row that
+//     publishes nothing sits in a keyed-permuted anonymous block. See the ORDERING
+//     section below and ADR 0255.
+//
 // TWO DELIBERATE FAIL-CLOSED CHOICES, because this is a privacy boundary, not a
 // rendering detail:
 //   1. AN UNKNOWN STATE DRAWS AS A BLACK HOLE. A fourth enum value added later and not
@@ -44,6 +51,8 @@
 // Proof: ../../tests/visible_projects_feed.mjs
 'use strict';
 
+const { randomBytes } = require('node:crypto');
+
 const { pool: defaultPool } = require('../../src/module-api');
 const { publishableSql } = require('./publish-gate');
 
@@ -103,21 +112,88 @@ function feedShapeFor(project) {
   return anonymous;
 }
 
-// The feed's hard ceiling. Until R06 the listing was bounded by an Archon choosing to
-// feature a project; the swap to `publishable` replaced that human bound with self-service,
-// on a route that is public, CORS-open, unauthenticated AND drives one outbound stats fetch
-// per row. A cap is the cheap half of that trade — the honest half is pagination, which is
-// its own task; this constant only stops the tail from being unbounded meanwhile. Set far
-// above the live catalog, so it truncates nothing today.
-const PUBLIC_FEED_MAX_PROJECTS = 500;
-
-// Every project ON THE MAP, in the public projection (no owner_github_id, no status).
-// `visibility` is projected because feedShapeFor() derives each row's state + orb from it;
-// it is spent there and never reaches the wire. created_at is the LISTED date — when the
-// hub first catalogued the row, not when the project began (task 1002778). updated_at may
-// sort but never projects: feature toggles and client re-registration bump it, so as a
-// public "last updated" it would lie. `description` is the publish BAR, spent in the
-// predicate, never a card field.
+// ── HOW THE FEED IS ORDERED, and why ordering is a privacy question ──────────
+//
+// A public list's ORDER BY is a covert column. Every row's position is the result of a
+// comparison, and enough comparisons reconstruct the key they were made on. Until task
+// 1003561 this feed sorted `featured DESC, updated_at DESC` — and `updated_at` is a
+// column the projection below deliberately WITHHOLDS, because as a public "last updated"
+// it would lie. Sorting by a withheld column publishes it anyway, one comparison at a time.
+//
+// For an identified row that is merely redundant. For a BLACK HOLE it defeats
+// STEALTH_ANONYMOUS_KEEPS above. That allow-list refuses to carry ANY stable per-project
+// key, precisely so an observer who kept yesterday's feed cannot diff it against today's
+// to name the project that went stealth — and then the ordering handed them exactly that.
+// A position is stable enough to follow one black hole across snapshots; it sits among
+// NAMED neighbours whose own order is visible, which brackets the hidden row between two
+// known timestamps; and it MOVES the moment the hidden project is touched. Black holes
+// are supposed to be interchangeable and silent. Sorted by their own timestamps they were
+// individually trackable and audibly alive.
+//
+// THE RULE THIS FILE NOW HOLDS: a row may be ordered only by what it publishes.
+//   • An IDENTIFIED row publishes `created_at` and `origin`, so it sorts by those, under
+//     `featured` (ADR 0182 D3's one remaining job — ranking). That order is a pure
+//     function of the wire payload: a reader holding nothing but the response can
+//     reproduce it, which is the strongest available statement that the sort leaks nothing
+//     the rows did not already say.
+//   • An ANONYMOUS row publishes nothing, so it is ordered by nothing about itself. The
+//     black holes are collated into ONE TRAILING BLOCK and permuted by a keyed hash: they
+//     neighbour no named row, so position carries no correlation, and the permutation
+//     re-deals on a fixed period so position is not a durable handle either.
+//
+// The decision, the alternatives weighed, and the two leaks this does NOT close (existence
+// is public by design, and the identified set still CHANGES when a project goes stealth)
+// are in ADR 0255.
+
+// The states that render IDENTIFIED — derived from ORB_BY_STATE rather than re-listed, so
+// the SQL and feedShapeFor() can never disagree about who is anonymous. A disagreement is
+// not cosmetic: it would position a row by a `created_at` that its own wire row, redacted
+// moments later, does not carry. Fail-closed in the SAME direction as orbStateOf() — a
+// state this file does not know is not identified.
+const IDENTIFIED_STATES = Object.freeze(
+  Object.keys(ORB_BY_STATE).filter((state) => state !== FALLBACK_PROJECT_STATE),
+);
+
+// The same fact, as SQL. Built only from string literals this file owns — never a caller's.
+const IDENTIFIED_SQL = `(visibility IN (${IDENTIFIED_STATES.map((s) => `'${s}'`).join(', ')}))`;
+
+// How often the anonymous block is re-dealt. Within one period the permutation is stable,
+// so the pages of one listing agree with each other; across periods the whole block is
+// re-permuted, so a rank held today is not the same black hole's rank tomorrow. That
+// rotation is what stops POSITION from quietly becoming the stable per-project key the
+// payload goes to such lengths to refuse.
+const ANONYMOUS_ORDER_EPOCH_MS = 24 * 60 * 60 * 1000;
+
+// The permutation key, and its SECRECY is the load-bearing part. Origins are guessable —
+// they are domain names — so a salt an observer could predict would let them hash their
+// candidate origins, match the ranks and de-anonymise the entire block in one pass.
+// Random per process, because this value only ever ORDERS rows: nothing persists it,
+// compares it across restarts or reads it back, so there is no key to configure,
+// distribute or leak, and a restart simply re-deals early.
+const ANONYMOUS_ORDER_KEY = randomBytes(16).toString('hex');
+
+// The salt for one listing: the secret, then the current epoch. Bound as a query
+// PARAMETER, never interpolated into SQL. PURE given `now`.
+function anonymousOrderSalt(now = Date.now()) {
+  return `${ANONYMOUS_ORDER_KEY}:${Math.floor(now / ANONYMOUS_ORDER_EPOCH_MS)}`;
+}
+
+// The feed's per-request ceiling AND its default page size — deliberately one number.
+//
+// It bounds FAN-OUT, not merely response size: this route is public, CORS-open and
+// unauthenticated, and each COLD row drives up to four outbound fetches at somebody else's
+// server, so the page size is the bound on how much traffic a single request can aim. The
+// other two bounds live elsewhere and both still hold — the per-IP limiter (120 reads/60s,
+// ADR 0252 §5.3) bounds how OFTEN, and project-stats.js's 10-minute per-origin cache bounds
+// the TOTAL. That cache is why paging deeper cannot multiply outbound traffic: a second
+// page reaches origins the cache would have covered anyway, and re-reading any page is free.
+//
+// DEFAULTING TO THE MAXIMUM IS THE COMPATIBILITY GUARANTEE, not laziness. 500 was the old
+// hard LIMIT, so a caller that sends no `?limit=` gets exactly what it got before — and one
+// consumer of this feed is a static orbs site in ANOTHER REPO that cannot be updated by
+// this commit. A smaller default would have silently shrunk somebody else's map.
+const PUBLIC_FEED_MAX_PAGE_SIZE = 500;
+
 // A PULLABLE row is on the map only once it has actually answered (R08, task 1002327;
 // ADR 0182 D5 via ADR 0252 §4). "Unreported => dark matter" is scoped, deliberately and
 // narrowly, to rows whose door the hub has never successfully read: a control-plane row
@@ -133,13 +209,39 @@ const PUBLIC_FEED_MAX_PROJECTS = 500;
 // empty the public map on deploy. Both halves are load-bearing.
 const DOOR_KNOWN_SQL = "(visibility_source = 'control-plane' OR visibility_reported_at IS NOT NULL)";
 
-async function listPublicProjects({ pool = defaultPool } = {}) {
+// Every project ON THE MAP, in the public projection (no owner_github_id, no status) — ONE
+// PAGE of it (task 1003561, which absorbed task 1003560). `visibility` is projected because
+// feedShapeFor() derives each row's state + orb from it; it is spent there and never reaches
+// the wire. created_at is the LISTED date — when the hub first catalogued the row, not when
+// the project began (task 1002778) — and it is now also the identified block's sort key,
+// which is exactly the point: the feed sorts by something it publishes. `description` is
+// the publish BAR, spent in the predicate, never a card field. `updated_at` no longer
+// appears at all — not in the projection, and since task 1003561 not in the ORDER BY either.
+//
+// PAGING IS `?limit=&offset=` (ADR 0119's contract, which this route was the last public
+// list to hold out on). No cursor, and that is 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 — would reintroduce the very side-channel the ORDER BY
+// above was rewritten to close. An offset encodes nothing about any row.
+//
+// The caller's window is clamped HERE as well as at the route, because this is a
+// module-public function and the ceiling is a fan-out bound: it must not depend on every
+// future caller remembering to pass one.
+async function listPublicProjects({ pool = defaultPool, limit = PUBLIC_FEED_MAX_PAGE_SIZE, offset = 0, now = Date.now() } = {}) {
+  const size = Number.isInteger(limit) && limit > 0
+    ? Math.min(limit, PUBLIC_FEED_MAX_PAGE_SIZE)
+    : PUBLIC_FEED_MAX_PAGE_SIZE;
+  const from = Number.isInteger(offset) && offset > 0 ? offset : 0;
   const { rows } = await pool.query(
     `SELECT origin, name, tagline, art_url, type, template, created_at, visibility
        FROM platform_identity_projects
       WHERE status = 'active' AND ${publishableSql()} AND ${DOOR_KNOWN_SQL}
-      ORDER BY featured DESC, updated_at DESC
-      LIMIT ${PUBLIC_FEED_MAX_PROJECTS}`,
+      ORDER BY ${IDENTIFIED_SQL} DESC,
+               (${IDENTIFIED_SQL} AND featured) DESC,
+               (CASE WHEN ${IDENTIFIED_SQL} THEN created_at END) DESC,
+               (CASE WHEN ${IDENTIFIED_SQL} THEN origin ELSE md5(origin || $1::text) END) ASC
+      LIMIT $2::int OFFSET $3::int`,
+    [anonymousOrderSalt(now), size, from],
   );
   return rows;
 }
@@ -148,11 +250,15 @@ module.exports = {
   ORB_BY_STATE,
   FALLBACK_PROJECT_STATE,
   STEALTH_ANONYMOUS_KEEPS,
+  IDENTIFIED_STATES,
+  IDENTIFIED_SQL,
+  ANONYMOUS_ORDER_EPOCH_MS,
+  anonymousOrderSalt,
   orbStateOf,
   orbForState,
   isStealthProject,
   feedShapeFor,
-  PUBLIC_FEED_MAX_PROJECTS,
+  PUBLIC_FEED_MAX_PAGE_SIZE,
   DOOR_KNOWN_SQL,
   listPublicProjects,
 };

package/modules/platform-identity/routes/my-projects.js

@@ -106,6 +106,10 @@ module.exports = function myProjectsRoutes() {
       // project's API discovery index through the same cached enrichment the
       // catalog uses (no hub table stores it). Best-effort: a project that does
       // not answer gets null, never a failed listing.
+      // The address is CONTAINED to the project's own origin before it ever
+      // reaches this list (project-stats.js:hallOrigin, task 1003670 / ADR 0254)
+      // — a remote instance may advertise any hall it likes, and this route
+      // renders one into an href just as the public feed does.
       let stats = {};
       try {
         stats = await projectStats.getProjectStats(rows.map((m) => m.project_origin).filter(Boolean));

package/modules/platform-identity/routes/projects.js

@@ -5,6 +5,8 @@
 //                                (active + publishable), each carrying its `state`
 //                                and `orb` render type, stealth rows anonymised
 //                                server-side, dark matter excluded (ADR 0182 D2a/D3).
+//                                Paged `?limit=&offset=` (ADR 0119), defaulting to the
+//                                whole 500-row ceiling so pre-paging callers are unchanged.
 //                                The PATH keeps the old word: it is a rank:public,
 //                                CORS-open URL that a static site and other origins
 //                                already fetch, and renaming it would break them for
@@ -30,7 +32,8 @@ const projectCatalog = require('../project-catalog');
 const projectStats = require('../project-stats');
 const inviteAuthz = require('../invite-authz');
 
-const { pool, requireBuilder, requirePermission, validateOrRespond, parseId, corsPublicGet } = api;
+const { pool, requireBuilder, requirePermission, validateOrRespond, parseId, corsPublicGet,
+  parsePagination, pageMeta } = api;
 const log = api.logger('platform-identity');
 
 // a catalog origin's host, the way the hub's sky joins it to an owned instance
@@ -233,9 +236,24 @@ module.exports = function projectsRoutes() {
   // provisioned) and replaced it with "whoever points a domain at us", which is what makes
   // the ceiling load-bearing rather than prudent. It runs BEFORE the handler, so a refused
   // read costs no query and no fetch.
-  router.get('/projects/featured', api.publicProjectFeedRateLimit, async (_req, res) => {
+  //
+  // PAGING DOES NOT RAISE THE CEILING IT SITS UNDER (task 1003561, absorbing task
+  // 1003560). `?limit=` only ever SHRINKS a page — parsePagination clamps it to the same
+  // 500 that used to be a silent hard truncation — so no request can aim more fan-out
+  // than one could before. `?offset=` reaches further down the catalog, and the only
+  // thing that costs is origins project-stats.js would have cached anyway: its 10-minute
+  // per-origin TTL, not the request count, is what bounds total outbound traffic. What
+  // paging BUYS is that the 501st project stops being invisible with nothing on the wire
+  // saying so.
+  router.get('/projects/featured', api.publicProjectFeedRateLimit, async (req, res) => {
     try {
-      const projects = await pi.listPublicProjects({ pool });
+      // Default page = the whole ceiling, so a caller that sends no params (the static
+      // orbs site in another repo, the apex landing band) gets exactly what it got before.
+      const { limit, offset } = parsePagination(req, {
+        defaultLimit: pi.PUBLIC_FEED_MAX_PAGE_SIZE,
+        maxLimit: pi.PUBLIC_FEED_MAX_PAGE_SIZE,
+      });
+      const projects = await pi.listPublicProjects({ pool, limit, offset });
       // A stealth project is on the map ANONYMOUSLY (ADR 0182 D2a), so its origin
       // is kept out of both enrichments below: asking its own public API for its
       // builders and their avatars would put identity on the wire, and tell that
@@ -282,6 +300,13 @@ module.exports = function projectsRoutes() {
       // rebuilds the row from an allow-list of the two keys a black hole may carry
       // (ADR 0182 D2a). Redacting any earlier would be silently undone by the
       // spreads above.
+      // `page` is ADR 0119's block, added beside the existing `projects` key rather than
+      // wrapping it: every consumer destructures `data.projects` (Explore, the projects
+      // hub sky, the apex band, the generated client, a static orbs site in another repo),
+      // so this is additive on the wire and breaks none of them. A caller learns there is
+      // more the standard way — `projects.length === page.limit` means ask for the next
+      // offset. No `total`: counting is a second pass over the same predicate for a number
+      // nothing reads today, and pageMeta() makes it optional for exactly that reason.
       res.json({
         projects: projects.map((p) => pi.feedShapeFor({
           ...p,
@@ -289,6 +314,7 @@ module.exports = function projectsRoutes() {
           ...(stats[p.origin] || projectStats.NULL_STATS),
           ...planetOf(p),
         })),
+        page: pageMeta(limit, offset),
       });
     } catch (err) {
       console.error('[platform-identity] GET /projects/featured', err);

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.566",
+  "version": "1.19.568",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.566",
+      "version": "1.19.568",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.566",
+  "version": "1.19.568",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/src/module-api.js

@@ -49,7 +49,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.566'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.568'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');