@bongos/core 1.19.417 → 1.19.419

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

@@ -0,0 +1,236 @@
+// modules/platform-identity/routes/connections.js — the connection graph API
+// (R19, task 1002295 / goal 1000045 criterion C6; ADR 0202).
+//
+// EVERY ROUTE HERE IS OWN-SCOPED. The acting account is always
+// req.builder.github_id — the session — and no route reads its subject from a
+// query, body or path parameter. The counterparty is named by HANDLE (the
+// public address, ADR 0171 D8) or by the connection row's own id; neither is a
+// way to act AS someone else. tests/own_scope_guard.mjs holds that structurally.
+//
+//   POST   /connections               — ask. Body { handle, note? }. 201
+//                                       { status: 'pending' } whether the row
+//                                       was written or SWALLOWED by the 90-day
+//                                       decline cooldown: the two answers are
+//                                       identical on purpose (ADR 0202 D2 §2).
+//                                       404 — not 403 — for a private or absent
+//                                       target, because 403 confirms the handle.
+//   GET    /connections               — my accepted connections. count is the
+//                                       array's own length (no hidden remainder).
+//   GET    /connections/requests      — my inbox + outbox; stamps seen_at.
+//   GET    /connections/degree/:handle — the viewer-relative label 0|1|2|3|null
+//                                       plus the mutuals it is computed from.
+//                                       An OWN-SCOPE read (D4 §4): this is how a
+//                                       viewer-relative number coexists with the
+//                                       viewer-independent public profile read.
+//   POST   /connections/:id/accept    — addressee only. 404 for anyone else.
+//   POST   /connections/:id/decline   — addressee only, SILENT (204). 404 else.
+//   DELETE /connections/:id           — remove an accepted row (either side) or
+//                                       cancel a pending one (requester only).
+//
+// A CONNECTION IS NEVER AUTHORITY (ADR 0016 / ADR 0141). Nothing here reads or
+// writes rank, credits, admission or permission; the numbers are descriptive.
+//
+// no-store on every response: these payloads are privacy-filtered per viewer and
+// a hide or a visibility flip must beat any cache (ADR 0171 D5).
+//
+// Reaches core only through the doorway (ADR 0083).
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const pi = require('../platform-identity');
+const conn = require('../connections');
+const { isAccountVisible } = require('../account-visibility');
+
+const { pool, requireBuilder, validateOrRespond, parsePagination } = api;
+const log = api.logger('platform-identity');
+
+// A connection row id is a bigserial. Anything else is answered 404 rather than
+// 400, for the same reason a wrong-owner id is: the id space must not be probeable.
+// The length cap is load-bearing, not cosmetic: a 25-digit string is all digits
+// and would reach Postgres, where it raises 22003 (bigint out of range) and
+// surfaces as a 500 — a different answer for a different id, i.e. a probe.
+function connectionId(req) {
+  return /^\d{1,19}$/.test(String(req.params.id || '')) ? req.params.id : null;
+}
+
+// The caller's platform account, or a { fail } describing why they cannot take
+// part. profile_state = 'active' is the floor for the WHOLE feature (ADR 0202
+// D4 §1): a provisional account cannot send, cannot receive, and never appears
+// in a list or a frontier. This is about the CALLER, so it may say so plainly.
+async function actingAccount(builder) {
+  const githubId = builder && builder.github_id;
+  if (!pi.isNumericGithubId(githubId)) {
+    return { fail: ['no_platform_identity', { status: 400, message: 'this session has no platform account' }] };
+  }
+  const acct = await pi.getAccount(githubId, { pool });
+  if (!acct || acct.profile_state !== 'active') {
+    return { fail: ['profile_provisional', { status: 403, message: 'sign in to the platform once to activate your profile before connecting' }] };
+  }
+  return { githubId };
+}
+
+// Resolve a handle to a counterparty THIS VIEWER may address: publicly visible,
+// or a private account the viewer is already connected to (ADR 0202 D4 §2).
+// Everything else — unknown handle, provisional account, private stranger — is
+// the same null, and the caller answers 404 for all of them.
+async function visibleTarget(viewerGithubId, handle) {
+  const acct = await conn.findAccountByHandle(handle, { pool });
+  if (!acct) return null;
+  if (isAccountVisible(acct)) return acct;
+  if (acct.profile_state !== 'active') return null;
+  return (await conn.isConnectedTo(viewerGithubId, acct.github_id, { pool })) ? acct : null;
+}
+
+module.exports = function connectionRoutes() {
+  const router = express.Router();
+
+  // One prefix covers every route below (/connections and /connections/...).
+  router.use('/connections', (req, res, next) => {
+    res.set('Cache-Control', 'no-store');
+    next();
+  });
+
+  // rank: any-builder — MY accepted connections (own data, keyed on the session).
+  // Own scope, so the counterparty floors on profile_state alone: a private
+  // account you connected with appears here and in no public list (D4 §2).
+  router.get('/connections', requireBuilder, async (req, res) => {
+    try {
+      const me = await actingAccount(req.builder);
+      if (me.fail) return res.fail(...me.fail);
+      const { limit, offset } = parsePagination(req, { defaultLimit: conn.FANOUT_1, maxLimit: conn.FANOUT_1 });
+      const connections = await conn.listConnections({ githubId: me.githubId, limit, offset }, { pool });
+      // The count IS the array's length — never a raw total beside a filtered
+      // list, which is a leak by subtraction (ADR 0171 D4 / ADR 0202 D4).
+      res.json({ connections, count: connections.length });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'GET /connections failed');
+      res.fail('connections_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: any-builder — MY pending requests, both directions (own data).
+  router.get('/connections/requests', requireBuilder, async (req, res) => {
+    try {
+      const me = await actingAccount(req.builder);
+      if (me.fail) return res.fail(...me.fail);
+      const { incoming, outgoing } = await conn.listRequests({ githubId: me.githubId }, { pool });
+      res.json({ incoming, outgoing, incoming_count: incoming.length, outgoing_count: outgoing.length });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'GET /connections/requests failed');
+      res.fail('connection_requests_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: any-builder — the degree label between the CALLER and one handle, plus
+  // the mutuals it was computed from (own-scope read, D4 §4). Bounded by
+  // construction: degreeBetween caps every level and answers null past the caps.
+  router.get('/connections/degree/:handle', requireBuilder, async (req, res) => {
+    try {
+      const me = await actingAccount(req.builder);
+      if (me.fail) return res.fail(...me.fail);
+      const target = await visibleTarget(me.githubId, req.params.handle);
+      if (!target) return res.fail('connection_target_not_found', 404);
+      const out = await conn.degreeBetween(me.githubId, target.github_id, { pool });
+      res.json({
+        handle: target.handle,
+        degree: out.degree,
+        mutuals: out.mutuals,
+        mutual_count: out.mutuals.length,
+        truncated: out.truncated,
+      });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'GET /connections/degree/:handle failed');
+      res.fail('connection_degree_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: any-builder — ask to connect. The REQUESTER is always the session; the
+  // body names only who is being asked, and it names them by public handle.
+  router.post('/connections', requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      handle: { required: true, type: 'string', minLength: 1, maxLength: 39 },
+      note: { type: 'string', maxLength: conn.NOTE_MAX_CHARS },
+    })) return;
+    try {
+      const me = await actingAccount(req.builder);
+      if (me.fail) return res.fail(...me.fail);
+      const target = await visibleTarget(me.githubId, req.body.handle);
+      // Absent, provisional and private-stranger are ONE answer. A 403 would
+      // confirm the handle exists, which is the whole thing private protects.
+      if (!target) return res.fail('connection_target_not_found', 404);
+      if (String(target.github_id) === String(me.githubId)) {
+        return res.fail('cannot_connect_to_self', { status: 400, message: 'that is your own account' });
+      }
+      const out = await conn.requestConnection({
+        requesterGithubId: me.githubId,
+        addresseeGithubId: target.github_id,
+        note: req.body.note || null,
+      }, { pool });
+      if (out.outcome === 'already_open') {
+        return res.fail('connection_already_open', { status: 409, message: 'there is already a request or a connection between you' });
+      }
+      // 'created' and 'swallowed' answer IDENTICALLY — no id, no timestamps,
+      // nothing a caller could difference to learn they were declined before.
+      res.status(201).json({ status: 'pending' });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'POST /connections failed');
+      res.fail('connection_request_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: any-builder — accept a request addressed to ME. The addressee is the
+  // session; a row belonging to anyone else simply does not match, and the 404
+  // that follows is what stops a builder acting on someone else's connection.
+  router.post('/connections/:id/accept', requireBuilder, async (req, res) => {
+    const id = connectionId(req);
+    if (!id) return res.fail('connection_request_not_found', 404);
+    try {
+      const me = await actingAccount(req.builder);
+      if (me.fail) return res.fail(...me.fail);
+      const ok = await conn.acceptConnection({ id, githubId: me.githubId }, { pool });
+      if (!ok) return res.fail('connection_request_not_found', 404);
+      res.json({ status: 'accepted' });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'POST /connections/:id/accept failed');
+      res.fail('connection_accept_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: any-builder — decline a request addressed to ME. 204: the requester is
+  // never told, so there is nothing to return that they could ever observe.
+  router.post('/connections/:id/decline', requireBuilder, async (req, res) => {
+    const id = connectionId(req);
+    if (!id) return res.fail('connection_request_not_found', 404);
+    try {
+      const me = await actingAccount(req.builder);
+      if (me.fail) return res.fail(...me.fail);
+      const ok = await conn.declineConnection({ id, githubId: me.githubId }, { pool });
+      if (!ok) return res.fail('connection_request_not_found', 404);
+      res.status(204).end();
+    } catch (err) {
+      log.error({ err: err && err.message }, 'POST /connections/:id/decline failed');
+      res.fail('connection_decline_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: any-builder — remove an accepted connection (either side may end it)
+  // or cancel a pending request I sent. An ADDRESSEE ending a pending row is a
+  // decline, not a delete, and is 404'd here so the cooldown cannot be dodged.
+  router.delete('/connections/:id', requireBuilder, async (req, res) => {
+    const id = connectionId(req);
+    if (!id) return res.fail('connection_not_found', 404);
+    try {
+      const me = await actingAccount(req.builder);
+      if (me.fail) return res.fail(...me.fail);
+      const outcome = await conn.removeConnection({ id, githubId: me.githubId }, { pool });
+      if (!outcome) return res.fail('connection_not_found', 404);
+      res.json({ outcome });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'DELETE /connections/:id failed');
+      res.fail('connection_remove_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.417",
+  "version": "1.19.419",
   "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/bongos/db.js

@@ -733,6 +733,50 @@ async function revokeAllSessionsForBuilder(builderId) {
   return rowCount;
 }
 
+// ---------- own-scoped session self-service (task 1003341) ----------
+//
+// The three helpers below are the account holder's OWN remedy for a leaked
+// bearer, and every one of them carries `builder_id = $caller` in its WHERE
+// clause. That predicate is the isolation: an id belonging to somebody else
+// matches no row, so a caller who guesses a stranger's session id learns
+// nothing and changes nothing. src/bongos/routes/my-sessions.js is the only
+// caller and always passes req.builder.id — never a client-supplied value.
+
+// listActiveSessionsForBuilder — the live (unrevoked, unexpired) sessions on one
+// account, newest-used first. Returns only what a person needs to RECOGNISE a
+// session — where it came from, when it was minted, when it was last used, what
+// client held it. The `token` column is deliberately never selected: a list that
+// returned tokens would turn one stolen session into all of them.
+
+async function listActiveSessionsForBuilder(builderId) {
+  const { rows } = await pool.query(
+    `SELECT id, source, user_agent, created_at, last_used_at, expires_at
+       FROM builder_sessions
+      WHERE builder_id = $1
+        AND revoked_at IS NULL
+        AND (expires_at IS NULL OR expires_at > now())
+      ORDER BY last_used_at DESC, id DESC`,
+    [builderId]
+  );
+  return rows;
+}
+
+// revokeSessionForBuilder — kill ONE session the caller owns. The own-scoped twin
+// of revokeSessionById: same effect, but it can only ever reach a row on the
+// caller's own account. Returns 1 when a session was killed, 0 when the id was
+// already revoked, expired, unknown, or somebody else's — the four cases are
+// deliberately indistinguishable to the caller.
+
+async function revokeSessionForBuilder(sessionId, builderId) {
+  const { rowCount } = await pool.query(
+    `UPDATE builder_sessions
+        SET revoked_at = now()
+      WHERE id = $1 AND builder_id = $2 AND revoked_at IS NULL`,
+    [sessionId, builderId]
+  );
+  return rowCount;
+}
+
 // -------------------------------------------------------------------------
 // Versions
 // -------------------------------------------------------------------------
@@ -994,6 +1038,8 @@ module.exports = {
   revokeSession,
   revokeSessionById,
   revokeAllSessionsForBuilder,
+  listActiveSessionsForBuilder,
+  revokeSessionForBuilder,
   hasCliSession,
   SESSION_TTL_MS,
   LIVE_RANK_LADDER,

package/src/bongos/route-rank-check.js

@@ -197,6 +197,16 @@ const EXPECTED_RANKS = {
   // session revocation (kill another builder's / all sessions)
   'POST /auth/revoke': 'perm:auth.session.revoke',
   'POST /auth/revoke-all': 'perm:auth.session.revoke',
+  // deliberately any-builder (task 1003341) — the OWN-scoped half of the same
+  // capability. These reach only the caller's own sessions (every statement is
+  // keyed on req.builder.id), so a rank floor here would just put an Archon back
+  // between a person and their own leaked token, which is the gap they close.
+  // Pinned in BOTH directions: an accidental rank/permission gate would silently
+  // re-break the self-serve remedy, and a widening to `public` would hand an
+  // anonymous caller a sign-out button.
+  'GET /me/sessions': 'any-builder',
+  'POST /me/sessions/revoke': 'any-builder',
+  'POST /me/sessions/revoke-all': 'any-builder',
   // forensic surfaces
   'GET /audit-log': 'perm:audit_log.read',
   'GET /builders/roster': 'perm:builder.roster.read',

package/src/bongos/routes/my-sessions.js

@@ -0,0 +1,128 @@
+// src/bongos/routes/my-sessions.js — a builder's own auth sessions: see them, kill them.
+//
+// WHY. A CLI bearer refreshes to now()+24h on every authenticated call (the
+// refresh-on-use UPDATE in db-kernel.js lookupSession), so a token that keeps
+// being used never expires on its own. Until these routes existed the only
+// remedy for a LEAKED one was POST /auth/revoke-all, gated on the admin
+// `auth.session.revoke` atom — so the victim had to find an Archon to sign them
+// out, and a single-owner self-hosted instance may not have a second Archon at
+// all. That is the gap this file closes: the account holder gets the remedy
+// directly, without anybody's permission but their own.
+//
+// THE INVARIANT, and the only thing that really matters when editing this file:
+// the account is ALWAYS req.builder.id, resolved by requireBuilder from the
+// session the caller actually presented. It is never read from the query
+// string, the request body, or the path. Every statement underneath carries
+// `builder_id = <caller>` in its WHERE clause, so an id belonging to somebody
+// else matches no row: a caller who guesses a stranger's session id gets
+// `revoked: 0` and learns nothing about whether it existed.
+//
+// WHY ITS OWN FILE rather than three more routes in routes/auth.js. The
+// cross-builder admin pair next door legitimately takes its target from the
+// request body — that is what makes it an admin route. Keeping the own-scoped
+// half in a separate file lets tests/own_session_revoke.mjs assert the
+// no-caller-named-id rule over this source WHOLE, with no carve-out for a
+// neighbouring route to hide behind. routes/auth.js is also the largest file in
+// the directory; this work does not belong in it.
+//
+// The token value is never selected, never logged, and never returned — a list
+// that handed back tokens would turn one stolen session into all of them.
+//
+// The 24h sliding refresh itself is deliberately left alone here; ADR 0206
+// records why an absolute ceiling is a separate decision from this remedy.
+
+const express = require('express');
+const auth = require('../auth');
+const db = require('../db');
+const { validateOrRespond } = require('./_helpers');
+const log = require('../logger').logger.child({ src: 'my-sessions' });
+
+// A bigserial id as the client may spell it. Matched (and then PASSED) as a
+// string rather than coerced through Number: a bigint above 2^53 would lose
+// precision on the way through, and a parameterized comparison against a bigint
+// column takes the text form without complaint.
+const SESSION_ID_RE = /^[0-9]{1,19}$/;
+
+// The list shape a person needs to RECOGNISE one of their own sessions: where it
+// came from, when it was minted, when it was last used, what client held it —
+// plus which row is the very request being served, so the UI can warn before
+// somebody signs out the browser they are reading the page in.
+function presentSession(row, currentSessionId) {
+  return {
+    id: String(row.id),
+    source: row.source,
+    user_agent: row.user_agent ?? null,
+    created_at: row.created_at,
+    last_used_at: row.last_used_at,
+    expires_at: row.expires_at,
+    current: currentSessionId !== null && String(row.id) === currentSessionId,
+  };
+}
+
+// The id of the session THIS request authenticated with, as a string, or null
+// when the auth layer did not leave one (no live row can then be marked current,
+// which is the safe direction — the UI simply omits the "this is you" badge).
+function currentSessionId(req) {
+  const id = req.gdsSession && req.gdsSession.session_id;
+  return id === undefined || id === null ? null : String(id);
+}
+
+module.exports = function buildMySessionsRouter() {
+  const router = express.Router();
+
+  // GET /api/bongos/me/sessions — every live session on the CALLER's account.
+  // rank: any-builder (own identity only) — a builder owns their own sessions;
+  // the account is req.builder.id, never a caller-named one, so there is nothing
+  // here for a rank gate to protect.
+  router.get('/me/sessions', auth.requireBuilder, async (req, res) => {
+    try {
+      const rows = await db.listActiveSessionsForBuilder(req.builder.id);
+      const current = currentSessionId(req);
+      res.json({ sessions: rows.map((row) => presentSession(row, current)) });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'GET /me/sessions failed');
+      res.fail('list_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /api/bongos/me/sessions/revoke — kill ONE of the caller's own sessions.
+  // Body: { session_id }. Response: { ok, revoked: 0|1 }. Revoking the session
+  // that made the request is allowed and immediate: the response is written from
+  // a request that already authenticated, and the next call with that token
+  // fails. `revoked: 0` covers "already gone", "never existed" and "not yours"
+  // alike — the caller must not be able to probe for other people's session ids.
+  // rank: any-builder (own identity only) — the WHERE clause is the boundary.
+  router.post('/me/sessions/revoke', auth.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, { session_id: {} })) return;
+    const raw = req.body && req.body.session_id;
+    if (raw === undefined || raw === null || !SESSION_ID_RE.test(String(raw))) {
+      return res.fail('bad_session_id', { status: 400, message: 'session_id must be a positive integer id from GET /me/sessions' });
+    }
+    try {
+      const revoked = await db.revokeSessionForBuilder(String(raw), req.builder.id);
+      res.json({ ok: true, revoked });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'POST /me/sessions/revoke failed');
+      res.fail('revoke_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /api/bongos/me/sessions/revoke-all — sign out everywhere. Kills EVERY
+  // live session on the caller's account, the one making the request included.
+  // That total sweep is the point: this is the button somebody presses when they
+  // believe a token has leaked, and a remedy that spared one session would leave
+  // them guessing which. They sign in again afterwards. Response: { ok, revoked }.
+  // rank: any-builder (own identity only) — the sweep is keyed on req.builder.id.
+  router.post('/me/sessions/revoke-all', auth.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {})) return;
+    try {
+      const revoked = await db.revokeAllSessionsForBuilder(req.builder.id);
+      res.json({ ok: true, revoked });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'POST /me/sessions/revoke-all failed');
+      res.fail('revoke_all_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};

package/src/bongos/routes.js

@@ -22,6 +22,10 @@ const buildInstanceRouter = require('./routes/instance');
 const buildAuthRouter = require('./routes/auth');
 const buildGithubRouter = require('./routes/github');
 const buildMeRouter = require('./routes/me');
+// The own-scoped session self-service (list / revoke one / sign out everywhere,
+// task 1003341). Its own router rather than three more routes on the /me
+// aggregator or the admin pair in routes/auth.js — see that file's header.
+const buildMySessionsRouter = require('./routes/my-sessions');
 const buildBuildersRouter = require('./routes/builders');
 // The LIFECYCLE routes (tasks · claims · versions · done-when · goals ·
 // dependencies · gate-approvals · analytics) carved into modules/lifecycle/
@@ -124,6 +128,7 @@ function buildGdsRouter() {
   router.use(buildAuthRouter());
   router.use(buildGithubRouter());
   router.use(buildMeRouter());
+  router.use(buildMySessionsRouter());
   router.use(buildBuildersRouter());
   // tasks · claims · versions · done-when · goals · dependencies · analytics now
   // mount via moduleLoader.mountModuleRoutes below (lifecycle module, BV1.R86) —

package/src/module-api.js

@@ -33,7 +33,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.417'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.419'; // 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');