@bongos/core 1.18.3 → 1.18.18

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

@@ -0,0 +1,151 @@
+// modules/platform-identity/hub-keys.js — the hub's assertion-signing keys +
+// EdDSA assertion minting (ADR 0141 §1, task #1002108).
+//
+// For CLI federation, the hub runs the GitHub device flow (its own app), then hands
+// the CLI a short-lived, audience-scoped SIGNED ASSERTION that the instance verifies
+// OFFLINE — so /sso/token stays browser-flow-only + server-to-server, and CLI login
+// needs no instance->hub call at exchange time.
+//
+// Signing is ASYMMETRIC (Ed25519): the hub holds the private key; instances hold
+// only the PUBLIC key (provisioned into their env). This is the deliberate split
+// from the per-client shared secret (which authenticates an instance TO the hub):
+// a compromised instance holds no signing key, so it can never forge an assertion
+// another instance would accept. node:crypto has Ed25519 built in — no dependency,
+// no PKI service.
+//
+// The assertion is a compact JWT (alg=EdDSA). The wire format is mirrored, by
+// necessity, in the instance-side verifier (src/bongos/auth.js verifyHubAssertion)
+// — the two sides live across the core<->module boundary and cannot share code
+// (ADR 0091 §2 boundary-forced duplication). Keep them in lockstep:
+//   token = base64url(JSON(header)) "." base64url(JSON(payload)) "." base64url(sig)
+//   header  = { alg: "EdDSA", typ: "JWT" }
+//   payload = { iss:"cloudbongos-hub", aud:<client_id>, sub:<github_id>,
+//               github_login, display_name, avatar_url, iat, exp, jti }
+//   sig     = Ed25519(privkey, utf8(`${b64u(header)}.${b64u(payload)}`))
+'use strict';
+
+const crypto = require('node:crypto');
+const api = require('../../src/module-api');
+
+const { resolveEnv } = api;
+
+// Assertion lifetime — deliberately short (~120s): a human runs the CLI exchange
+// within seconds of approving in the browser, so a tight window bounds replay.
+const ASSERTION_TTL_MS = 120 * 1000;
+const ISSUER = 'cloudbongos-hub';
+
+const b64uJson = (obj) => Buffer.from(JSON.stringify(obj), 'utf8').toString('base64url');
+
+// Generate a fresh Ed25519 keypair, exported as single-line base64(DER) strings
+// suitable for env vars. The hub operator runs this ONCE and places the private
+// key in the hub's web.env (<PREFIX>_HUB_SIGNING_KEY); the public key is provisioned
+// into each federated instance (<PREFIX>_HUB_PUBLIC_KEY). Returns { privateKeyB64,
+// publicKeyB64 }.
+function generateHubKeypair() {
+  const { privateKey, publicKey } = crypto.generateKeyPairSync('ed25519');
+  return {
+    privateKeyB64: privateKey.export({ type: 'pkcs8', format: 'der' }).toString('base64'),
+    publicKeyB64: publicKey.export({ type: 'spki', format: 'der' }).toString('base64'),
+  };
+}
+
+// Load the hub's Ed25519 PRIVATE signing key from env (base64 of the PKCS8 DER).
+// Returns a KeyObject or null when unset (→ device federation is "not configured").
+function loadHubSigningKey({ env } = {}) {
+  const b64 = env ? env.HUB_SIGNING_KEY : resolveEnv('HUB_SIGNING_KEY');
+  if (!b64) return null;
+  try {
+    return crypto.createPrivateKey({ key: Buffer.from(String(b64), 'base64'), format: 'der', type: 'pkcs8' });
+  } catch (err) {
+    console.error('[platform-identity] HUB_SIGNING_KEY is set but unreadable:', err.message);
+    return null;
+  }
+}
+
+function hubSigningConfigured() {
+  return !!loadHubSigningKey();
+}
+
+// The hub's PUBLIC key (base64 of the SPKI DER), derived from the private key, for
+// the GET /sso/pubkey endpoint. Returns null when the private key is unset.
+function hubPublicKeyB64() {
+  const priv = loadHubSigningKey();
+  if (!priv) return null;
+  const pub = crypto.createPublicKey(priv);
+  return pub.export({ type: 'spki', format: 'der' }).toString('base64');
+}
+
+// Mint an audience-scoped, short-lived EdDSA assertion for a federated client. The
+// payload carries IDENTITY ONLY (never a rank). `nowMs`/`jti` are injectable for
+// deterministic tests. Returns the compact token string.
+function mintHubAssertion(
+  { clientId, githubId, githubLogin, displayName, avatarUrl },
+  { signingKey, nowMs, jti } = {},
+) {
+  const key = signingKey || loadHubSigningKey();
+  if (!key) throw new Error('hub signing key not configured');
+  const iat = Math.floor((nowMs ?? Date.now()) / 1000);
+  const header = { alg: 'EdDSA', typ: 'JWT' };
+  const payload = {
+    iss: ISSUER,
+    aud: String(clientId),
+    sub: String(githubId),
+    github_login: githubLogin,
+    display_name: displayName ?? null,
+    avatar_url: avatarUrl ?? null,
+    iat,
+    exp: iat + Math.floor(ASSERTION_TTL_MS / 1000),
+    jti: jti || crypto.randomBytes(12).toString('base64url'),
+  };
+  const signingInput = `${b64uJson(header)}.${b64uJson(payload)}`;
+  const sig = crypto.sign(null, Buffer.from(signingInput, 'utf8'), key).toString('base64url');
+  return `${signingInput}.${sig}`;
+}
+
+// The purpose marker that distinguishes a back-channel LOGOUT token from a login
+// assertion. Both are hub-signed EdDSA JWTs, but a logout token carries `purpose`
+// + NO identity fields, and a login assertion carries identity + NO `purpose` —
+// so neither verifier accepts the other's tokens (the instance login verifier
+// requires github_login; the logout verifier requires this purpose). Task 1002238.
+const LOGOUT_PURPOSE = 'backchannel-logout';
+
+// Mint an audience-scoped, short-lived EdDSA BACK-CHANNEL LOGOUT token for a
+// federated client (ADR 0144, task 1002238). The hub sends this to a federated
+// instance's /auth/backchannel-logout when a builder signs out of the hub, so the
+// instance can revoke that builder's local session too (federated single-logout).
+// Carries ONLY the subject (github_id) + the purpose marker — never identity, a
+// rank, or a session token (the ADR 0016 trust boundary holds here too: the hub
+// says "sign this github_id out", the instance decides what that means locally).
+// Same asymmetric signing + ~120s TTL + aud-binding as mintHubAssertion, so a
+// token minted for one instance can't be replayed against another. nowMs/jti
+// injectable for deterministic tests.
+function mintHubLogoutToken({ clientId, githubId }, { signingKey, nowMs, jti } = {}) {
+  const key = signingKey || loadHubSigningKey();
+  if (!key) throw new Error('hub signing key not configured');
+  const iat = Math.floor((nowMs ?? Date.now()) / 1000);
+  const header = { alg: 'EdDSA', typ: 'JWT' };
+  const payload = {
+    iss: ISSUER,
+    aud: String(clientId),
+    sub: String(githubId),
+    purpose: LOGOUT_PURPOSE,
+    iat,
+    exp: iat + Math.floor(ASSERTION_TTL_MS / 1000),
+    jti: jti || crypto.randomBytes(12).toString('base64url'),
+  };
+  const signingInput = `${b64uJson(header)}.${b64uJson(payload)}`;
+  const sig = crypto.sign(null, Buffer.from(signingInput, 'utf8'), key).toString('base64url');
+  return `${signingInput}.${sig}`;
+}
+
+module.exports = {
+  ASSERTION_TTL_MS,
+  ISSUER,
+  LOGOUT_PURPOSE,
+  generateHubKeypair,
+  loadHubSigningKey,
+  hubSigningConfigured,
+  hubPublicKeyB64,
+  mintHubAssertion,
+  mintHubLogoutToken,
+};

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

@@ -0,0 +1,114 @@
+-- platform_identity_001_tables.sql — the `platform-identity` module's DB slice
+-- (ADR 0141 §2, task #1002106). The Cloud Bongos hub identity-provider store:
+-- platform accounts + an SSO client registry + single-use authorization codes.
+--
+-- The hub is an IDENTITY provider, NOT an authority (ADR 0016 / ADR 0141): none of
+-- these tables carry a rank, credits, or admission — only the stable GitHub identity
+-- (github_id, login, display name, avatar). Authority stays computed locally on each
+-- federated instance.
+--
+-- Module migrations are ADDITIVE and NAMESPACED (ADR 0083 §Decision #5): every
+-- object lives under the platform_identity_ prefix, there is no down-migration, and
+-- the filename is platform_identity_-prefixed (ADR 0108 §5) so its stem can never
+-- collide with a core / instance / other-module migration across repos.
+-- `scripts/migrate.sh` discovers + applies this ONLY when the platform-identity
+-- module is enabled in config/modules.json (i.e. on the hub).
+--
+-- Idempotent: safe to re-run.
+
+BEGIN;
+
+-- ---------------------------------------------------------------------------
+-- platform_identity_accounts — the platform account, keyed on the stable GitHub
+-- user id. One row per human who has ever signed in on the hub. Identity only.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS platform_identity_accounts (
+  id            bigserial PRIMARY KEY,
+
+  -- GitHub's numeric user id — the stable, rename-proof key the whole federation
+  -- pivots on (a login can change; the id does not). UNIQUE = one account per human.
+  github_id     bigint NOT NULL UNIQUE,
+
+  github_login  text NOT NULL,
+  display_name  text,
+  avatar_url    text,
+
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now()
+);
+
+-- ---------------------------------------------------------------------------
+-- platform_identity_sso_clients — registered federated projects (each an OAuth
+-- client of the hub). Provisioning (task #1002109) writes a row per hosted
+-- instance; the client_secret is stored ONLY as a hash — the plaintext lives in
+-- the instance's env and never returns from the hub.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS platform_identity_sso_clients (
+  id               bigserial PRIMARY KEY,
+
+  -- The public client identifier the instance presents at /sso/authorize + /sso/token.
+  client_id        text NOT NULL UNIQUE,
+
+  -- SHA-256 hash (hex) of the client secret. NEVER the plaintext. Verified with a
+  -- constant-time compare at /sso/token. The secret is high-entropy (256-bit random,
+  -- generated by provisioning), so a fast hash is sufficient (no password-dictionary
+  -- surface); the hash-at-rest means a DB read leak does not expose live secrets.
+  secret_hash      text NOT NULL,
+
+  -- Human-facing project name (for the hub Explore/catalog + audit).
+  name             text NOT NULL,
+
+  -- The exact-match allow-list of redirect URIs this client may receive a code at.
+  -- An /sso/authorize redirect_uri (and the /sso/token redirect_uri) MUST appear
+  -- here verbatim — the open-redirect guard (ADR 0141 §2 invariant #3).
+  redirect_uris    text[] NOT NULL DEFAULT '{}',
+
+  -- The instance's public origin (advisory / display; the authority is redirect_uris).
+  origin           text,
+
+  -- The account that owns this project (advisory attribution; NOT an authority).
+  owner_github_id  bigint,
+
+  status           text NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'suspended')),
+
+  created_at       timestamptz NOT NULL DEFAULT now(),
+  updated_at       timestamptz NOT NULL DEFAULT now()
+);
+
+-- ---------------------------------------------------------------------------
+-- platform_identity_auth_codes — single-use authorization codes (~60s TTL). Minted
+-- at /sso/authorize (browser leg), redeemed once at /sso/token (server-to-server).
+-- Stores only a HASH of the opaque code (the code is a bearer secret) + an identity
+-- snapshot + the binding (client_id, github_id, redirect_uri). Single-use is enforced
+-- by the atomic redeem (UPDATE ... WHERE consumed_at IS NULL RETURNING) in the domain.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS platform_identity_auth_codes (
+  id            bigserial PRIMARY KEY,
+
+  -- SHA-256 hash (hex) of the opaque authorization code. UNIQUE so a hash collision
+  -- or double-insert is impossible; the plaintext code is never stored.
+  code_hash     text NOT NULL UNIQUE,
+
+  -- Binding: the code is valid ONLY when redeemed by this client for this account,
+  -- at the redirect_uri it was minted against.
+  client_id     text NOT NULL,
+  github_id     bigint NOT NULL,
+  redirect_uri  text NOT NULL,
+
+  -- Identity snapshot returned on redeem — identity ONLY, never a rank.
+  github_login  text NOT NULL,
+  display_name  text,
+  avatar_url    text,
+
+  expires_at    timestamptz NOT NULL,
+  -- NULL until redeemed; the single-use guard flips it to now() atomically.
+  consumed_at   timestamptz,
+  created_at    timestamptz NOT NULL DEFAULT now()
+);
+
+-- Hot path: the redeem filters on code_hash (already UNIQUE-indexed) + expiry; this
+-- index also backs a cheap TTL sweep of stale/consumed rows.
+CREATE INDEX IF NOT EXISTS platform_identity_auth_codes_expiry
+  ON platform_identity_auth_codes (expires_at);
+
+COMMIT;

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

@@ -0,0 +1,18 @@
+-- platform_identity_002_client_origin_index.sql — index sso_clients by origin so the
+-- CLI device-flow mint can resolve a client from the USER-TYPED instance origin
+-- (ADR 0141 §1, task #1002108 security fix). The audience of a CLI assertion is now
+-- resolved server-side from the origin the user typed, via this registry lookup —
+-- NOT from a client_id the (untrusted) instance manifest supplies. That closes the
+-- confused-deputy where a malicious `bongos login <evil>` could harvest a real-hub-
+-- signed assertion scoped to a VICTIM instance. `origin` was advisory in _001; this
+-- promotes it to an authoritative lookup key.
+--
+-- Additive + platform_identity_-namespaced (ADR 0083 §5). Idempotent.
+
+BEGIN;
+
+CREATE INDEX IF NOT EXISTS platform_identity_sso_clients_origin
+  ON platform_identity_sso_clients (origin)
+  WHERE status = 'active';
+
+COMMIT;

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

@@ -0,0 +1,42 @@
+-- platform_identity_003_project_memberships.sql — the hub's cross-project membership
+-- directory (ADR 0141 §3, task #1002111). A federated instance posts a server-to-
+-- server "check-in" on every sign-in (browser OR CLI): "this github_id builds on
+-- project P, with this COARSE role". The hub upserts a row here. This is what makes a
+-- CLI-only project appear in a builder's "My Projects" with no browser session ever
+-- created against the hub.
+--
+-- Identity + a coarse role ONLY (ADR 0141: identity federated, authority local) — the
+-- role is owner|builder|visitor, NEVER a rank. The project is keyed by client_id (the
+-- sso_clients row that authenticated the check-in); a later projects catalog
+-- (task #1002110) relates by client_id/origin for display.
+--
+-- Additive + platform_identity_-namespaced (ADR 0083 §5). Idempotent.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS platform_identity_project_memberships (
+  id           bigserial PRIMARY KEY,
+
+  -- The project, identified by the sso_client that reported the membership.
+  client_id    text NOT NULL,
+
+  -- The builder, by their stable GitHub id (joins to platform_identity_accounts).
+  github_id    bigint NOT NULL,
+
+  -- COARSE role — never a rank. 'pending' is reserved for pre-seeded invitations
+  -- (task #1002115) that resolve on accept.
+  role         text NOT NULL DEFAULT 'builder'
+    CHECK (role IN ('owner', 'builder', 'visitor', 'pending')),
+
+  joined_at    timestamptz NOT NULL DEFAULT now(),
+  last_active  timestamptz NOT NULL DEFAULT now(),
+
+  -- One membership row per (project, builder).
+  UNIQUE (client_id, github_id)
+);
+
+-- "My Projects" reads all memberships for one account.
+CREATE INDEX IF NOT EXISTS platform_identity_project_memberships_github
+  ON platform_identity_project_memberships (github_id);
+
+COMMIT;

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

@@ -0,0 +1,44 @@
+-- platform_identity_004_projects.sql — the hub projects catalog (ADR 0141 §5, task
+-- #1002110). One row per project the hub knows about, powering the public "Explore"
+-- showcase (featured projects) + the join key for "My Projects" display. A federated
+-- project is auto-catalogued when it registers as an sso_client; an Archon curates
+-- the `featured` flag.
+--
+-- Keyed by `origin` (the project's public URL) — the natural project identity that
+-- joins to sso_clients.origin and, through it, to project_memberships. Public,
+-- non-authoritative directory metadata only (no rank/credits).
+--
+-- Additive + platform_identity_-namespaced (ADR 0083 §5). Idempotent.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS platform_identity_projects (
+  id               bigserial PRIMARY KEY,
+
+  -- The project's public origin (e.g. https://mercury.cloudbongos.com). UNIQUE — one
+  -- catalog row per project; the join key to sso_clients / memberships.
+  origin           text NOT NULL UNIQUE,
+
+  name             text NOT NULL,
+  tagline          text,           -- a short one-liner for the Explore card
+  art_url          text,           -- optional cover art / logo
+
+  owner_github_id  bigint,         -- advisory attribution (not an authority)
+
+  -- 'hidden' keeps a row out of every listing (e.g. a deprovisioned project) without
+  -- deleting its history.
+  status           text NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'hidden')),
+
+  -- The Archon-curated Explore flag. Only featured + active projects show publicly.
+  featured         boolean NOT NULL DEFAULT false,
+
+  created_at       timestamptz NOT NULL DEFAULT now(),
+  updated_at       timestamptz NOT NULL DEFAULT now()
+);
+
+-- The Explore listing reads featured + active projects.
+CREATE INDEX IF NOT EXISTS platform_identity_projects_featured
+  ON platform_identity_projects (featured)
+  WHERE featured = true AND status = 'active';
+
+COMMIT;

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

@@ -0,0 +1,42 @@
+-- platform_identity_005_builder_activity.sql — the hub's cross-project builder
+-- activity store (ADR 0141 §4, task #1002113). Each federated project reports a
+-- per-builder rollup (credits, tasks shipped, karma, rank held, disciplines,
+-- recency); the hub upserts one row per (project, builder). This is the data plane
+-- behind the INTERNAL, Archon-only scouting view (task #1002114) — it UPGRADES the
+-- coarse ADR 0127 fleet metrics (two gauges keyed on a mutable handle) to a stable
+-- github_id-keyed store.
+--
+-- Distinction from the identity federation: this rollup DOES carry rank_held +
+-- credits, but as descriptive analytics for an internal talent directory (consent
+-- via the platform T&C) — it is NEVER read as authority to grant anything on any
+-- instance. Authority stays local (ADR 0141 / ADR 0016).
+--
+-- Additive + platform_identity_-namespaced (ADR 0083 §5). Idempotent.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS platform_identity_builder_project_activity (
+  id             bigserial PRIMARY KEY,
+
+  -- The project (the sso_client that reported) + the builder (stable github id).
+  client_id      text NOT NULL,
+  github_id      bigint NOT NULL,
+
+  -- Descriptive talent signals — a snapshot, eventually-consistent, non-authoritative.
+  credits        integer NOT NULL DEFAULT 0,
+  tasks_shipped  integer NOT NULL DEFAULT 0,
+  karma          integer NOT NULL DEFAULT 0,
+  rank_held      text,
+  disciplines    text[] NOT NULL DEFAULT '{}',
+
+  last_active    timestamptz NOT NULL DEFAULT now(),
+  updated_at     timestamptz NOT NULL DEFAULT now(),
+
+  UNIQUE (client_id, github_id)
+);
+
+-- Scouting aggregates across all projects for one builder.
+CREATE INDEX IF NOT EXISTS platform_identity_builder_activity_github
+  ON platform_identity_builder_project_activity (github_id);
+
+COMMIT;

package/modules/platform-identity/module.json

@@ -0,0 +1,18 @@
+{
+  "key": "platform-identity",
+  "title": "Platform identity (hub IdP)",
+  "description": "The Cloud Bongos hub identity-provider surface (ADR 0141): platform accounts, an SSO client registry, and an OAuth authorization-code login handoff so one platform account reaches any hosted project's builders hall with no second GitHub sign-in. Identity ONLY — the hub never mints or carries rank/credits/admission (the ADR 0016 trust boundary). Enabled ONLY on the hub instance (cloudbongos.com); ordinary hosted + self-hosted instances leave it off, so it adds zero attack surface for the common case.",
+  "coreVersion": "^1.14.0",
+  "default": false,
+  "author": "Cloud Bongos",
+  "origin": "Cloud Bongos platform (cloudbongos.com)",
+  "license": "AGPL-3.0",
+  "maintainer": "Cloud Bongos maintainers",
+  "contributes": {
+    "routes": ["sso", "projects", "my-projects", "scouting"],
+    "migrations": true,
+    "pollers": ["code-sweep"]
+  },
+  "provides": ["platform-identity.hub"],
+  "consumes": []
+}