@bongos/core 1.19.1025 → 1.19.1027

package/modules/platform-identity/migrations/platform_identity_025_guilds.sql

@@ -0,0 +1,100 @@
+-- platform_identity_025_guilds.sql — guilds on the hub (task 1002300, R24;
+-- ADR 0336 D1, whose migration sketch this is, amended by ADR 0337 D4.4).
+--
+-- WHAT THIS IS. Three tables: the guild, its members, and the open invites and
+-- join requests between them. A guild is account-global, so it lives beside
+-- connections in platform-identity rather than beside core goal_members (a goal
+-- is an instance-local work container; a guild is a cross-project group of
+-- people). A standalone instance never enables this module, so it has no guild
+-- surface at all.
+--
+-- THE SHAPE CARRIES THE RULES, so no route has to remember them:
+--   * visibility has NO DEFAULT — the creator chooses public or unlisted, and a
+--     silent default would decide a privacy question for them (ADR 0336 D1);
+--   * there is no creator column — the owner ROW is the authority, and a
+--     permanent "created by" would keep a departed creator tied to the guild;
+--   * membership_kind, never `role` — ADR 0174 reserves that word for the crafts;
+--   * exactly one owner per guild is a partial unique index, held by the
+--     database. Because it is checked row by row and a partial index cannot be
+--     deferred, a transfer is two statements in one transaction (ADR 0336 D2);
+--   * shown_publicly has NO DEFAULT — it records what the join card showed
+--     (ADR 0336 D4 §3), so every insert must say it;
+--   * counted_in_totals DEFAULTS TRUE — ADR 0337 D4.4: every member counts in the
+--     guild's rounded totals unless they switch it off for that guild. The
+--     request row carries the requester's choice until the owner accepts.
+--
+-- Leaving, removal and dissolving HARD-DELETE (ADR 0336 D2, the ADR 0202 D2
+-- reason); the FKs cascade so a dissolved guild takes its open requests with it.
+--
+-- NOTHING HERE IS AUTHORITY (ADR 0016 / ADR 0141). No rank, credit or admission
+-- path reads these tables; a guild membership admits nobody anywhere.
+--
+-- Additive + platform_identity_-namespaced (ADR 0083 §5). CREATE only, so the
+-- previous release still runs against this schema. Idempotent.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS platform_identity_guilds (
+  id          bigserial PRIMARY KEY,
+  -- The /g/<slug> key, fixed at creation (ADR 0336 D6): the handle charset,
+  -- lowercase, 2-39 characters. Canonical form is enforced here as well as in
+  -- the domain, so a direct write cannot store a slug the URL cannot carry.
+  slug        text NOT NULL CONSTRAINT platform_identity_guilds_slug_form
+                CHECK (slug ~ '^[a-z0-9][a-z0-9-]{0,37}[a-z0-9]$'),
+  name        text NOT NULL CONSTRAINT platform_identity_guilds_name_len
+                CHECK (length(name) BETWEEN 1 AND 80),
+  description text CONSTRAINT platform_identity_guilds_description_len
+                CHECK (description IS NULL OR length(description) <= 500),
+  visibility  text NOT NULL CHECK (visibility IN ('public', 'unlisted')),
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  updated_at  timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX IF NOT EXISTS uniq_platform_identity_guilds_slug
+  ON platform_identity_guilds (lower(slug));
+
+CREATE TABLE IF NOT EXISTS platform_identity_guild_members (
+  guild_id          bigint NOT NULL REFERENCES platform_identity_guilds(id) ON DELETE CASCADE,
+  github_id         bigint NOT NULL,
+  membership_kind   text NOT NULL DEFAULT 'member' CHECK (membership_kind IN ('owner', 'member')),
+  shown_publicly    boolean NOT NULL,
+  counted_in_totals boolean NOT NULL DEFAULT true,
+  joined_at         timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (guild_id, github_id)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS uniq_platform_identity_guild_owner
+  ON platform_identity_guild_members (guild_id) WHERE membership_kind = 'owner';
+CREATE INDEX IF NOT EXISTS platform_identity_guild_members_account
+  ON platform_identity_guild_members (github_id);
+
+CREATE TABLE IF NOT EXISTS platform_identity_guild_requests (
+  id                bigserial PRIMARY KEY,
+  guild_id          bigint NOT NULL REFERENCES platform_identity_guilds(id) ON DELETE CASCADE,
+  github_id         bigint NOT NULL,
+  kind              text NOT NULL CHECK (kind IN ('invite', 'request')),
+  status            text NOT NULL DEFAULT 'pending'
+                      CHECK (status IN ('pending', 'accepted', 'rejected', 'cancelled', 'expired')),
+  counted_in_totals boolean NOT NULL DEFAULT true,
+  seen_at           timestamptz,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  resolved_at       timestamptz
+);
+-- At most one OPEN row per (guild, person), whichever direction it runs, so an
+-- invite and a request for the same pair collide instead of racing.
+CREATE UNIQUE INDEX IF NOT EXISTS uniq_platform_identity_guild_requests_open
+  ON platform_identity_guild_requests (guild_id, github_id) WHERE status = 'pending';
+CREATE INDEX IF NOT EXISTS platform_identity_guild_requests_account
+  ON platform_identity_guild_requests (github_id, status);
+
+COMMENT ON TABLE platform_identity_guilds IS
+  'Hub guilds (ADR 0336). visibility is the owner''s choice: public (a public page, takes join requests) or unlisted (no public existence, invites only). No creator column: the owner row in platform_identity_guild_members is the authority. Descriptive only, never authority (ADR 0016).';
+
+COMMENT ON COLUMN platform_identity_guild_members.shown_publicly IS
+  'This member agreed to appear on the guild''s PUBLIC page (ADR 0336 D4). Set from the visibility the join card showed; changing the guild''s visibility changes only the owner''s flag, never another member''s.';
+
+COMMENT ON COLUMN platform_identity_guild_members.counted_in_totals IS
+  'The member''s per-guild switch for the guild''s rounded totals (ADR 0337 D4.4). On by default; the member may turn it off for any guild at any time.';
+
+COMMENT ON COLUMN platform_identity_guild_requests.status IS
+  'pending -> accepted | rejected (declined: SILENT, and a 90-day cooldown that swallows a re-ask of the same kind) | cancelled | expired (30 days, resolved at write time). The connections lifecycle, verbatim (ADR 0336 D3, ADR 0202 D2).';
+
+COMMIT;

package/modules/platform-identity/module.json

@@ -10,7 +10,7 @@
   "maintainer": "Cloud Bongos maintainers",
   "maintenance": { "status": "core-maintained" },
   "contributes": {
-    "routes": ["sso", "projects", "my-projects", "scouting", "profile", "public-profile", "connections", "community-search"],
+    "routes": ["sso", "projects", "my-projects", "scouting", "profile", "public-profile", "connections", "community-search", "community-leaderboard", "guilds", "guilds-public"],
     "migrations": true,
     "pollers": ["code-sweep", "visibility-pull"]
   },

package/modules/platform-identity/read-rate-limit.js

@@ -0,0 +1,62 @@
+// modules/platform-identity/read-rate-limit.js — a per-IP read cap for an
+// UNAUTHENTICATED public GET in this module. The global limiter meters writes
+// only, and core's per-IP sliding window (src/bongos/middleware/rate-limit.js
+// perIpSlidingWindow) reaches modules only as ready-built instances on the
+// doorway (ADR 0209: an instance per budget), none of which is this module's.
+// This is the module-side twin of that function — same 429 envelope and
+// headers — written once (task 1002978) and mounted by the community reads
+// (routes/community-leaderboard.js, routes/community-search.js) and the public
+// guild read (routes/guilds-public.js).
+// routes/public-profile.js and routes/sso.js still carry older vendored copies.
+'use strict';
+
+const SWEEP_EVERY_MS = 5 * 60 * 1000;
+// Bounds the bucket map between sweeps: rotating source addresses (an IPv6
+// block) must not grow the heap without limit on an unauthenticated route.
+const MAX_TRACKED_IPS = 10000;
+
+// createReadRateLimit({ scope, limit, windowMs, maxTrackedIps }) → Express
+// middleware allowing `limit` requests per IP per sliding `windowMs`, then 429
+// rate_limited with Retry-After. `scope` names the budget in the response so a
+// client can tell which cap it hit. Buckets live in this closure: one budget
+// per call. The map is kept in least-recently-seen order, so at the tracking
+// cap the IP evicted is the one idle longest — O(1), no scan on the hot path.
+function createReadRateLimit({ scope, limit, windowMs = 60 * 1000, maxTrackedIps = MAX_TRACKED_IPS }) {
+  const buckets = new Map(); // ip -> timestamp[], least recently seen first
+
+  const sweepTimer = setInterval(() => {
+    const cutoff = Date.now() - windowMs;
+    for (const [k, arr] of buckets) {
+      while (arr.length && arr[0] < cutoff) arr.shift();
+      if (arr.length === 0) buckets.delete(k);
+    }
+  }, SWEEP_EVERY_MS);
+  if (typeof sweepTimer.unref === 'function') sweepTimer.unref();
+
+  return function readRateLimit(req, res, next) {
+    const now = Date.now();
+    const key = req.ip || req.socket?.remoteAddress || 'unknown';
+    let bucket = buckets.get(key);
+    if (bucket) {
+      buckets.delete(key); // re-inserted below: most recently seen goes last
+    } else {
+      if (buckets.size >= maxTrackedIps) buckets.delete(buckets.keys().next().value);
+      bucket = [];
+    }
+    buckets.set(key, bucket);
+    const cutoff = now - windowMs;
+    while (bucket.length && bucket[0] < cutoff) bucket.shift();
+    if (bucket.length >= limit) {
+      const retryAfter = Math.max(1, Math.ceil((bucket[0] + windowMs - now) / 1000));
+      res.set('Retry-After', String(retryAfter));
+      res.set('X-RateLimit-Scope', scope);
+      res.set('X-RateLimit-Limit', String(limit));
+      res.set('X-RateLimit-Window-Seconds', String(windowMs / 1000));
+      return res.fail('rate_limited', 429, { scope, retry_after_seconds: retryAfter });
+    }
+    bucket.push(now);
+    return next();
+  };
+}
+
+module.exports = { createReadRateLimit, MAX_TRACKED_IPS };

package/modules/platform-identity/routes/community-leaderboard.js

@@ -0,0 +1,69 @@
+// modules/platform-identity/routes/community-leaderboard.js — GET
+// /community/leaderboard, the PUBLIC windowed leaderboard behind the hub's
+// /community page (D3, docs/specs/bongos-v1-community-tab.md; task 1002978,
+// goal 1000110 CT2). The sibling of routes/community-search.js: same module,
+// same public posture. Who appears and how a window is counted live entirely in
+// ../community-leaderboard.js; this file is the HTTP shell — validation, the
+// per-IP read cap, the response envelope. It never reads a session, so the
+// board is the same for every viewer.
+//
+// Reaches core only through the doorway (ADR 0083).
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const leaderboard = require('../community-leaderboard');
+const { createReadRateLimit } = require('../read-rate-limit');
+
+const { pool, corsPublicGet } = api;
+
+const READ_RATE_LIMIT = 60; // per IP per minute — the community-search budget
+const READ_RATE_SCOPE = 'community-leaderboard-read';
+const leaderboardReadRateLimit = createReadRateLimit({ scope: READ_RATE_SCOPE, limit: READ_RATE_LIMIT });
+
+module.exports = function communityLeaderboardRoutes() {
+  const router = express.Router();
+
+  router.use('/community/leaderboard', corsPublicGet('/community/leaderboard'));
+
+  // rank: public — the cross-project leaderboard (?window=7d|30d|365d|all,
+  // default all; ?discipline=; ?limit=&offset=). Eligibility is the privacy
+  // matrix's numbers predicate (active + public + stats shown); the recruiting
+  // opt-out does not apply. no-store: hide must beat the cache (ADR 0171 D5).
+  // Rollout note: until a builder's first changed report after snapshot history
+  // began, their whole lifetime total counts inside every window (spec D2's
+  // missing-baseline-is-zero rule) — expected on day one, and self-correcting.
+  router.get('/community/leaderboard', leaderboardReadRateLimit, async (req, res) => {
+    const window = req.query.window === undefined || req.query.window === ''
+      ? leaderboard.DEFAULT_WINDOW
+      : req.query.window;
+    if (!leaderboard.isWindow(window)) {
+      return res.fail('bad_window', { status: 400, message: `window must be one of: ${leaderboard.WINDOWS.join(', ')}` });
+    }
+    const discipline = (typeof req.query.discipline === 'string' ? req.query.discipline : '').trim();
+    if (discipline.length > leaderboard.MAX_DISCIPLINE_CHARS) {
+      return res.fail('discipline_too_long', { status: 400, message: `discipline must be at most ${leaderboard.MAX_DISCIPLINE_CHARS} characters` });
+    }
+    try {
+      const board = await leaderboard.listLeaderboard({
+        window, discipline, limit: req.query.limit, offset: req.query.offset, pool,
+      });
+      res.set('Cache-Control', 'no-store');
+      res.json({
+        window: board.window,
+        since: board.since,
+        discipline: discipline || null,
+        count: board.results.length,
+        results: board.results,
+        page: { limit: board.limit, offset: board.offset },
+      });
+    } catch (err) {
+      api.logger('platform-identity').error({ err: err && err.message }, 'GET /community/leaderboard failed');
+      res.fail('leaderboard_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};
+
+module.exports._internals = { READ_RATE_LIMIT, READ_RATE_SCOPE };

package/modules/platform-identity/routes/community-search.js

@@ -16,6 +16,7 @@
 const express = require('express');
 const api = require('../../../src/module-api');
 const builderSearch = require('../builder-search');
+const { createReadRateLimit } = require('../read-rate-limit');
 
 const { pool, corsPublicGet } = api;
 
@@ -33,39 +34,11 @@ const log = {
 
 // Per-IP read cap for this UNAUTHENTICATED route (the public-profile.js R05
 // posture: the global limiter only meters WRITES, so an uncapped scraper could
-// otherwise run the trigram leg at line rate). Vendored, not shared — the core
-// /public/* limiter is not on the doorway, and each public GET here owns its
-// own budget rather than reaching into a sibling module's copy.
+// otherwise run the trigram leg at line rate). Its own budget, built by the
+// module's shared factory (task 1002978) rather than a vendored copy.
 const READ_RATE_WINDOW_MS = 60 * 1000;
 const READ_RATE_LIMIT = 60;
-const buckets = new Map(); // ip -> timestamp[]
-
-const sweepTimer = setInterval(() => {
-  const cutoff = Date.now() - READ_RATE_WINDOW_MS;
-  for (const [k, arr] of buckets) {
-    while (arr.length && arr[0] < cutoff) arr.shift();
-    if (arr.length === 0) buckets.delete(k);
-  }
-}, 5 * 60 * 1000);
-if (typeof sweepTimer.unref === 'function') sweepTimer.unref();
-
-function searchReadRateLimit(req, res, next) {
-  const now = Date.now();
-  const key = req.ip || req.socket?.remoteAddress || 'unknown';
-  let bucket = buckets.get(key);
-  if (!bucket) { bucket = []; buckets.set(key, bucket); }
-  const cutoff = now - READ_RATE_WINDOW_MS;
-  while (bucket.length && bucket[0] < cutoff) bucket.shift();
-  if (bucket.length >= READ_RATE_LIMIT) {
-    const retryAfter = Math.max(1, Math.ceil((bucket[0] + READ_RATE_WINDOW_MS - now) / 1000));
-    res.set('Retry-After', String(retryAfter));
-    res.set('X-RateLimit-Scope', 'community-search-read');
-    res.set('X-RateLimit-Limit', String(READ_RATE_LIMIT));
-    return res.fail('rate_limited', 429, { scope: 'community-search-read', retry_after_seconds: retryAfter });
-  }
-  bucket.push(now);
-  return next();
-}
+const searchReadRateLimit = createReadRateLimit({ scope: 'community-search-read', limit: READ_RATE_LIMIT, windowMs: READ_RATE_WINDOW_MS });
 
 module.exports = function communitySearchRoutes() {
   const router = express.Router();

package/modules/platform-identity/routes/guilds-public.js

@@ -0,0 +1,57 @@
+// modules/platform-identity/routes/guilds-public.js — the PUBLIC guild read
+// (task 1002300, R24; ADR 0336 D4). Its own file because every route in
+// routes/guilds.js is own-scoped and held there by tests/own_scope_guard.mjs;
+// this one is deliberately not.
+//
+//   GET /guilds/:slug — a PUBLIC guild's name, description, public roster and
+//   size. 404 for an unknown slug AND for an unlisted guild, to everyone, its own
+//   members included: the read takes no viewer, so it cannot vary by one (the
+//   private-profile rule, ADR 0171 D4). Members reach an unlisted guild through
+//   the own-scope GET /guilds/:slug/members. The page at /g/<slug> is task
+//   1002301's; this is its read.
+//
+// Reaches core only through the doorway (ADR 0083).
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const guilds = require('../guilds');
+const { createReadRateLimit } = require('../read-rate-limit');
+
+const { pool } = api;
+
+// Resolved at call time, the community-search.js precedent: a proof that stubs a
+// partial doorway can still require() this file.
+let resolvedLog = null;
+function logError(msg) {
+  if (!resolvedLog) resolvedLog = typeof api.logger === 'function' ? api.logger('platform-identity') : { error: () => {} };
+  resolvedLog.error(msg);
+}
+
+// Per-IP read cap for this UNAUTHENTICATED route, its own budget. The global
+// limiter meters writes only, and a roster read maps handles to guilds, so an
+// uncapped scraper could walk the slug space at line rate.
+const guildReadRateLimit = createReadRateLimit({ scope: 'guild-public-read', limit: 120 });
+
+module.exports = function guildPublicRoutes() {
+  const router = express.Router();
+
+  // rank: public — a public guild's page data. The roster is the members who
+  // agreed to be shown AND whose own accounts are publicly visible (ADR 0336 D4);
+  // size is that roster's length. no-store: a hide or a visibility flip must beat
+  // every cache (ADR 0171 D5).
+  router.get('/guilds/:slug', guildReadRateLimit, async (req, res) => {
+    res.set('Cache-Control', 'no-store');
+    try {
+      const slug = guilds.lookupSlug(req.params.slug);
+      const out = slug ? await guilds.getPublicGuild(slug, { pool }) : null;
+      if (!out) return res.fail('guild_not_found', 404);
+      res.json({ guild: out.guild, members: out.members, size: out.size });
+    } catch (err) {
+      logError(`GET /guilds/:slug failed: ${err && err.message}`);
+      res.fail('guild_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};