@bongos/core 1.19.418 → 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.418",
+  "version": "1.19.419",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.418",
+      "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.418",
+  "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/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.418'; // 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');