@bongos/core 1.21.135 → 1.21.137

package/migrations/core_277_passkey_foundation.sql

@@ -0,0 +1,53 @@
+-- core_277 passkey foundation: credentials, per-builder user handle, challenge store
+-- Applied under task 1004750 (ADR 0382 D1, D6).
+--
+-- WHY. A hardware card (a WebAuthn passkey) is a second sign-in step an Archon can
+-- switch on per builder. Before any ceremony route can exist, the server needs three
+-- things to keep: the public half of each registered card, an opaque handle that
+-- stands in for the builder inside the card (never the email), and the challenges it
+-- has issued and not yet seen answered.
+--
+-- SHAPE.
+--  * passkey_credentials  one row per registered card. credential_id is the
+--    authenticator's own id (base64url) and is UNIQUE: a card can belong to one
+--    builder. sign_count is kept so a counter that goes backwards can be caught.
+--  * passkey_user_handles one random handle per builder, minted on first use.
+--  * passkey_challenges   short-lived, single-use. A row is DELETED when consumed;
+--    expires_at lets a sweep remove the ones nobody answered. builder_id is nullable
+--    because a sign-in ceremony starts before the builder is known.
+
+CREATE TABLE IF NOT EXISTS passkey_credentials (
+  id             bigserial PRIMARY KEY,
+  credential_id  text        NOT NULL UNIQUE,
+  builder_id     bigint      NOT NULL REFERENCES builders(id) ON DELETE CASCADE,
+  public_key     bytea       NOT NULL,
+  sign_count     bigint      NOT NULL DEFAULT 0,
+  transports     text[]      NOT NULL DEFAULT '{}',
+  aaguid         text,
+  nickname       text,
+  created_at     timestamptz NOT NULL DEFAULT now(),
+  last_used_at   timestamptz
+);
+
+CREATE INDEX IF NOT EXISTS idx_passkey_credentials_builder
+  ON passkey_credentials (builder_id);
+
+CREATE TABLE IF NOT EXISTS passkey_user_handles (
+  builder_id   bigint PRIMARY KEY REFERENCES builders(id) ON DELETE CASCADE,
+  user_handle  text   NOT NULL UNIQUE,
+  created_at   timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS passkey_challenges (
+  challenge   text        PRIMARY KEY,
+  purpose     text        NOT NULL CHECK (purpose IN ('register', 'authenticate')),
+  builder_id  bigint      REFERENCES builders(id) ON DELETE CASCADE,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  expires_at  timestamptz NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_passkey_challenges_expires
+  ON passkey_challenges (expires_at);
+
+INSERT INTO schema_migrations (version) VALUES ('core_277_passkey_foundation')
+  ON CONFLICT (version) DO NOTHING;

package/modules/hall-ui/public/settings-passkeys.js

@@ -0,0 +1,113 @@
+// modules/hall-ui/public/settings-passkeys.js — the "Security cards" panel on
+// /builders/settings (task 1004746, ADR 0382). List, add, rename, remove the
+// signed-in builder's FIDO cards. All identity is the server's session; this file
+// only drives the ceremony the browser library performs.
+(() => {
+  'use strict';
+
+  const API = '/api/bongos';
+  const { escapeHtml, $, fmtDate } = window.OTB;
+  const toast = (msg) => window.OTB.toast(msg);
+  const api = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
+  const toAuth = () => window.location.assign(`${API}/auth/web/start`);
+
+  const fail = (res) => new Error((res.data && res.data.message) || `HTTP ${res.status}`);
+
+  function rowHtml(c) {
+    const name = c.nickname || 'Unnamed card';
+    const used = c.last_used_at ? `last used ${escapeHtml(fmtDate(c.last_used_at))}` : 'never used';
+    return `<div class="sessions-row" data-id="${escapeHtml(c.credential_id)}">
+      <div class="sessions-row__main">
+        <strong>${escapeHtml(name)}</strong>
+        <span class="sessions-row__when">added ${escapeHtml(fmtDate(c.created_at))} · ${used}</span>
+      </div>
+      <button type="button" class="settings-btn settings-btn--quiet passkeys-rename">Rename</button>
+      <button type="button" class="settings-btn settings-btn--quiet passkeys-remove">Remove</button>
+    </div>`;
+  }
+
+  async function render() {
+    const res = await api.request('GET', `${API}/me/passkeys`);
+    if (res.status === 401) { toAuth(); return; }
+    if (!res.ok) throw fail(res);
+    const cards = (res.data && res.data.passkeys) || [];
+    const list = $('#passkeys-list');
+    list.innerHTML = cards.length ? cards.map(rowHtml).join('') : '<p class="settings-card__hint">No cards registered yet.</p>';
+    for (const row of list.querySelectorAll('.sessions-row')) {
+      const id = row.getAttribute('data-id');
+      row.querySelector('.passkeys-rename').addEventListener('click', () => rename(id, row));
+      row.querySelector('.passkeys-remove').addEventListener('click', () => remove(id));
+    }
+  }
+
+  async function rename(id, row) {
+    const current = row.querySelector('strong').textContent;
+    const next = window.prompt('Name this card', current === 'Unnamed card' ? '' : current);
+    if (next === null) return;
+    try {
+      const res = await api.request('POST', `${API}/me/passkeys/rename`, { body: { credential_id: id, nickname: next } });
+      if (!res.ok) throw fail(res);
+      await render();
+    } catch (err) { toast(`Could not rename that card: ${err.message}`); }
+  }
+
+  async function remove(id) {
+    if (!window.confirm('Remove this card? You can register it again later.')) return;
+    try {
+      const res = await api.request('POST', `${API}/me/passkeys/remove`, { body: { credential_id: id } });
+      if (!res.ok) throw fail(res);
+      toast('Card removed.');
+      await render();
+    } catch (err) { toast(`Could not remove that card: ${err.message}`); }
+  }
+
+  function loadBrowserLib() {
+    if (window.SimpleWebAuthnBrowser) return Promise.resolve(window.SimpleWebAuthnBrowser);
+    return new Promise((resolve, reject) => {
+      const s = document.createElement('script');
+      s.src = `${API}/me/passkeys/browser.js`;
+      s.onload = () => resolve(window.SimpleWebAuthnBrowser);
+      s.onerror = () => reject(new Error('could not load the card library'));
+      document.head.appendChild(s);
+    });
+  }
+
+  async function add() {
+    const btn = $('#passkeys-add');
+    const status = $('#passkeys-status');
+    btn.disabled = true;
+    status.textContent = 'Waiting for your card…';
+    try {
+      const lib = await loadBrowserLib();
+      if (!lib.browserSupportsWebAuthn()) throw new Error('this browser does not support security cards');
+      const opt = await api.request('POST', `${API}/me/passkeys/register/options`, { body: {} });
+      if (opt.status === 401) { toAuth(); return; }
+      if (!opt.ok) throw fail(opt);
+      const attestation = await lib.startRegistration({ optionsJSON: opt.data.options });
+      const nickname = $('#passkeys-nickname').value;
+      const ver = await api.request('POST', `${API}/me/passkeys/register/verify`, { body: { response: attestation, nickname } });
+      if (!ver.ok) throw fail(ver);
+      $('#passkeys-nickname').value = '';
+      status.textContent = '';
+      toast('Card added.');
+      await render();
+    } catch (err) {
+      status.textContent = '';
+      toast(`Could not add a card: ${err.name === 'NotAllowedError' ? 'cancelled or timed out' : err.message}`);
+    } finally {
+      btn.disabled = false;
+    }
+  }
+
+  async function setup() {
+    try {
+      await render();
+      $('#passkeys-scroll').hidden = false;
+      $('#passkeys-add').addEventListener('click', add);
+    } catch (err) {
+      toast(`Could not load your security cards: ${err.message}`);
+    }
+  }
+
+  setup();
+})();

package/modules/hall-ui/public/settings.html

@@ -171,6 +171,25 @@
               <p class="section-note">Ending a session takes effect immediately; the token stops working on its very next request.</p>
             </section>
 
+            <!-- SECURITY CARDS - register, rename and remove your FIDO hardware
+                 cards (task 1004746, ADR 0382). Rendered by settings-passkeys.js
+                 against /api/bongos/me/passkeys. -->
+            <section class="scroll" id="passkeys-scroll" aria-labelledby="passkeys-h" data-group="access" hidden>
+              <h2 id="passkeys-h" class="scroll__h">Security cards</h2>
+              <p class="scroll__lede">
+                Register a hardware security card (or a phone or laptop passkey) so it can
+                be asked for as a second check on sensitive actions. Registering a card
+                does not change how you sign in.
+              </p>
+              <div id="passkeys-list" class="sessions-list" aria-live="polite"></div>
+              <div class="settings-card">
+                <input type="text" id="passkeys-nickname" maxlength="60" placeholder="Name this card (optional)" aria-label="Card name">
+                <button type="button" class="settings-btn" id="passkeys-add">Add a card</button>
+                <span class="settings-status" id="passkeys-status" role="status" aria-live="polite"></span>
+              </div>
+              <p class="section-note">Hold the card to your reader or touch it when your browser asks. Keep more than one registered in case one is lost.</p>
+            </section>
+
             <!-- YOUR AUTOBONGOS RUNNER — which goals your own unattended runner
                  works (task 1004501). Rendered by settings-autobongos.js against
                  GET /autonomy/fence (your effective fence) and PUT
@@ -467,6 +486,7 @@
 <!-- task 1003341: the Active sessions panel. Its own file rather than more of
      settings.js, which sits close to the 1500-line size ratchet. -->
 <script src="/builders/settings-sessions.js?v=2026-08-29-sessions"></script>
+<script src="/builders/settings-passkeys.js?v=2026-10-15-passkeys"></script>
 <!-- task 1002514: the interaction-profile panel ("How Claude talks to you"), on
      the same precedent and for the same reason — settings.js is against the
      1500-line ratchet, and this panel shares nothing with the rest of the page. -->

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.135",
+  "version": "1.21.137",
   "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/release-notes.json

@@ -9812,5 +9812,17 @@
       "id": "1003462",
       "text": "Adds an Add-a-task form to the Goals page: pick an open goal, name the task, optional description. Sends POST /tasks unchanged; the server's rank floor, goal/version and closed-goal refusals render as sentences. States that a"
     }
+  ],
+  "1.21.136": [
+    {
+      "id": "1004750",
+      "text": "Groundwork for hardware-card sign-in: the database tables and storage code that remember registered cards and the short-lived one-time challenges. Nothing is visible to builders yet."
+    }
+  ],
+  "1.21.137": [
+    {
+      "id": "1004746",
+      "text": "Builders can now register, list, rename and remove a hardware security card from Settings."
+    }
   ]
 }

package/scripts/gds/run-unit-tests.js

@@ -232,6 +232,9 @@ const INTEGRATION = new Set([
   // admission reads' statements run on Postgres, and the hub's notice restamp and
   // listing. The DB-free sibling (application_lifecycle) interprets the same WHEREs.
   'invite_expiry_db',
+  // task 1004750 (ADR 0382 D6): passkey tables from the real migration — single-use
+  // challenges, TTL sweep, unique credential id, sign-count regression.
+  'passkey_foundation_db',
   // task 1004408: migration platform_identity_028 deletes the old hub invite's
   // pending rows before a cutoff it reads from the core_upgrades ledger. Only a real
   // engine runs the DO block, the numeric version compare and the one-shot guard.

package/src/bongos/passkeys.js

@@ -0,0 +1,153 @@
+// src/bongos/passkeys.js — passkey (WebAuthn) storage: credentials, the opaque user
+// handle, and the single-use challenge store (task 1004750, ADR 0382 D1/D6).
+//
+// This file is the foundation only: it keeps and hands back state. The registration
+// and sign-in ceremonies, and the routes that drive them, are their own tasks and
+// build on these functions with @simplewebauthn/server.
+//
+// A challenge is single-use: consumeChallenge DELETEs the row and returns it, so a
+// replay finds nothing. A challenge past its TTL is refused even before the sweep
+// has removed it.
+'use strict';
+
+const crypto = require('node:crypto');
+
+const CHALLENGE_TTL_SECONDS = 300;
+const MAX_CHALLENGE_TTL_SECONDS = 600;
+const PURPOSES = Object.freeze(['register', 'authenticate']);
+
+function defaultPool() { return require('./pool').pool; }
+
+function randomToken(bytes) { return crypto.randomBytes(bytes).toString('base64url'); }
+
+// A TTL is a positive whole number of seconds no longer than the ceiling, so a caller
+// forwarding an untrusted value cannot mint a long-lived (or already-dead) challenge.
+function clampTtlSeconds(ttl) {
+  const n = Math.floor(Number(ttl));
+  if (!Number.isFinite(n) || n <= 0) return CHALLENGE_TTL_SECONDS;
+  return Math.min(n, MAX_CHALLENGE_TTL_SECONDS);
+}
+
+// The clone check. A counter that does not advance is suspect, unless the card
+// does not keep one at all (stored and reported both zero).
+function counterAdvances(stored, reported) {
+  if (stored === 0 && reported === 0) return true;
+  return reported > stored;
+}
+
+// Mint and store a challenge. Returns { challenge, expiresAt }.
+async function createChallenge({ purpose, builderId = null, ttlSeconds = CHALLENGE_TTL_SECONDS, pool = defaultPool() } = {}) {
+  if (!PURPOSES.includes(purpose)) throw new Error(`passkeys: bad challenge purpose ${JSON.stringify(purpose)}`);
+  const challenge = randomToken(32);
+  // Housekeeping rides on issuing: expired rows are removed here, so the table is
+  // swept by use and needs no separate scheduler.
+  await sweepExpiredChallenges({ pool });
+  const { rows } = await pool.query(
+    `INSERT INTO passkey_challenges (challenge, purpose, builder_id, expires_at)
+     VALUES ($1, $2, $3, now() + make_interval(secs => $4::int))
+     RETURNING expires_at`,
+    [challenge, purpose, builderId, String(clampTtlSeconds(ttlSeconds))],
+  );
+  return { challenge, expiresAt: rows[0].expires_at };
+}
+
+// Take a challenge: delete it and return { purpose, builderId } if it was live, else
+// null. Pass expectPurpose (and expectBuilderId for a signed-in registration) and a
+// challenge issued for something else is refused. It is still spent: a wrong-purpose
+// presentation burns it rather than leaving it to be tried again.
+async function consumeChallenge(challenge, { expectPurpose = null, expectBuilderId = null, pool = defaultPool() } = {}) {
+  if (typeof challenge !== 'string' || !challenge) return null;
+  const { rows } = await pool.query(
+    `DELETE FROM passkey_challenges WHERE challenge = $1
+     RETURNING purpose, builder_id, (expires_at > now()) AS live`,
+    [challenge],
+  );
+  const r = rows[0];
+  if (!r || !r.live) return null;
+  if (expectPurpose != null && r.purpose !== expectPurpose) return null;
+  if (expectBuilderId != null && String(r.builder_id) !== String(expectBuilderId)) return null;
+  return { purpose: r.purpose, builderId: r.builder_id == null ? null : String(r.builder_id) };
+}
+
+// Remove every challenge past its TTL. Returns the number removed.
+async function sweepExpiredChallenges({ pool = defaultPool() } = {}) {
+  const r = await pool.query('DELETE FROM passkey_challenges WHERE expires_at <= now()');
+  return r.rowCount;
+}
+
+// The builder's opaque WebAuthn user handle, minted on first use. Never the email.
+async function getOrCreateUserHandle(builderId, { pool = defaultPool() } = {}) {
+  const { rows } = await pool.query(
+    `INSERT INTO passkey_user_handles (builder_id, user_handle) VALUES ($1, $2)
+     ON CONFLICT (builder_id) DO UPDATE SET builder_id = EXCLUDED.builder_id
+     RETURNING user_handle`,
+    [builderId, randomToken(32)],
+  );
+  return rows[0].user_handle;
+}
+
+async function addCredential({ builderId, credentialId, publicKey, signCount = 0, transports = [], aaguid = null, nickname = null }, { pool = defaultPool() } = {}) {
+  const { rows } = await pool.query(
+    `INSERT INTO passkey_credentials (credential_id, builder_id, public_key, sign_count, transports, aaguid, nickname)
+     VALUES ($1, $2, $3, $4, $5, $6, $7) RETURNING id, created_at`,
+    [credentialId, builderId, Buffer.from(publicKey), signCount, transports, aaguid, nickname],
+  );
+  return rows[0];
+}
+
+async function getCredentialById(credentialId, { pool = defaultPool() } = {}) {
+  const { rows } = await pool.query(
+    `SELECT id, credential_id, builder_id, public_key, sign_count, transports, aaguid, nickname, created_at, last_used_at
+       FROM passkey_credentials WHERE credential_id = $1`,
+    [credentialId],
+  );
+  return rows[0] || null;
+}
+
+async function listCredentials(builderId, { pool = defaultPool() } = {}) {
+  const { rows } = await pool.query(
+    `SELECT id, credential_id, transports, aaguid, nickname, created_at, last_used_at
+       FROM passkey_credentials WHERE builder_id = $1 ORDER BY created_at, id`,
+    [builderId],
+  );
+  return rows;
+}
+
+// Record a successful use. One guarded UPDATE both checks and writes, so two
+// concurrent assertions carrying the same counter cannot both pass and the stored
+// counter can never be lowered. A counter that does not advance (unless the card keeps
+// none) is a possible clone: nothing is written and the reason says why.
+async function recordUse(credentialId, newSignCount, { pool = defaultPool() } = {}) {
+  const r = await pool.query(
+    `UPDATE passkey_credentials SET sign_count = $2, last_used_at = now()
+      WHERE credential_id = $1 AND (($2 = 0 AND sign_count = 0) OR $2 > sign_count)`,
+    [credentialId, newSignCount],
+  );
+  if (r.rowCount > 0) return { ok: true };
+  const cred = await getCredentialById(credentialId, { pool });
+  return { ok: false, reason: cred ? 'sign_count_regressed' : 'unknown_credential' };
+}
+
+async function removeCredential(builderId, credentialId, { pool = defaultPool() } = {}) {
+  const r = await pool.query(
+    'DELETE FROM passkey_credentials WHERE builder_id = $1 AND credential_id = $2',
+    [builderId, credentialId],
+  );
+  return r.rowCount > 0;
+}
+
+// Rename a card. Scoped to the builder in the WHERE clause, so another builder's
+// credential id matches no row.
+async function renameCredential(builderId, credentialId, nickname, { pool = defaultPool() } = {}) {
+  const r = await pool.query(
+    'UPDATE passkey_credentials SET nickname = $3 WHERE builder_id = $1 AND credential_id = $2',
+    [builderId, credentialId, nickname],
+  );
+  return r.rowCount > 0;
+}
+
+module.exports = {
+  CHALLENGE_TTL_SECONDS, MAX_CHALLENGE_TTL_SECONDS, PURPOSES, clampTtlSeconds, counterAdvances,
+  createChallenge, consumeChallenge, sweepExpiredChallenges,
+  getOrCreateUserHandle, addCredential, getCredentialById, listCredentials, recordUse, removeCredential, renameCredential,
+};

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

@@ -0,0 +1,249 @@
+// src/bongos/routes/my-passkeys.js — a signed-in builder's own hardware cards:
+// register one, list them, rename one, remove one (task 1004746, ADR 0382 D3/D6).
+//
+// THE INVARIANT, as in my-sessions.js: the account is ALWAYS req.builder.id, taken
+// from the session the caller presented. It is never read from the body, query or
+// path, and every store call is keyed on it, so a credential id belonging to
+// somebody else matches nothing.
+//
+// A card is a second factor added AFTER normal sign-in (D2/D3); this file only
+// registers and manages cards. Nothing here switches a requirement on.
+//
+// Registration is two steps: `register/options` mints a single-use challenge bound
+// to the builder, `register/verify` consumes it (a replay or someone else's
+// challenge finds nothing) and stores the public half of the card. The private key
+// never leaves the card.
+
+const express = require('express');
+const path = require('node:path');
+const fs = require('node:fs');
+const auth = require('../auth');
+const { validateOrRespond, publicOrigin } = require('./_helpers');
+const log = require('../logger').logger.child({ src: 'my-passkeys' });
+
+const NICKNAME_MAX = 60;
+const CREDENTIAL_ID_RE = /^[A-Za-z0-9_-]{1,1024}$/;
+const MAX_CARDS_PER_BUILDER = 10;
+
+// The RP ID and origin are configuration, set once by the owner (ADR 0382 D7):
+// PASSKEY_ORIGIN and PASSKEY_RP_ID. Request headers are attacker-influenceable and
+// origin pinning is WebAuthn's whole protection, so the request is trusted ONLY for a
+// local development host; anywhere else, unset config means refuse, not guess.
+const LOCAL_HOST_RE = /^(localhost|127\.0\.0\.1|\[::1\]|[a-z0-9-]+\.localhost)$/i;
+function relyingParty(req) {
+  const rpName = process.env.PASSKEY_RP_NAME || 'Cloud Bongos';
+  let origin = process.env.PASSKEY_ORIGIN || null;
+  let rpID = process.env.PASSKEY_RP_ID || null;
+  if (!origin) {
+    const fromReq = publicOrigin(req);
+    let host = null;
+    try { host = new URL(fromReq).hostname; } catch { host = null; }
+    if (host && LOCAL_HOST_RE.test(host)) origin = fromReq;
+  }
+  if (!rpID && origin) { try { rpID = new URL(origin).hostname.replace(/^\[|\]$/g, ''); } catch { rpID = null; } }
+  return origin && rpID ? { origin, rpID, rpName } : null;
+}
+
+// The vendored browser bundle, resolved once. The package's exports map hides its
+// package.json, so walk up from the resolved entry to the package root instead.
+let bundleFile;
+function browserBundleFile() {
+  if (bundleFile !== undefined) return bundleFile;
+  bundleFile = null;
+  try {
+    let dir = path.dirname(require.resolve('@simplewebauthn/browser'));
+    for (let i = 0; i < 6 && !fs.existsSync(path.join(dir, 'dist', 'bundle')); i++) dir = path.dirname(dir);
+    const file = path.join(dir, 'dist', 'bundle', 'index.umd.min.js');
+    if (fs.existsSync(file)) bundleFile = file;
+  } catch { /* leave null */ }
+  return bundleFile;
+}
+
+function cleanNickname(raw) {
+  if (raw === undefined || raw === null) return { value: null };
+  if (typeof raw !== 'string') return { error: 'nickname must be text' };
+  const v = raw.replace(/\s+/g, ' ').trim();
+  if (v.length > NICKNAME_MAX) return { error: `nickname must be ${NICKNAME_MAX} characters or fewer` };
+  return { value: v || null };
+}
+
+function presentCard(row) {
+  return {
+    credential_id: row.credential_id,
+    nickname: row.nickname ?? null,
+    transports: row.transports || [],
+    created_at: row.created_at,
+    last_used_at: row.last_used_at ?? null,
+  };
+}
+
+// Dependencies are injectable so the route is testable without Postgres or a real
+// authenticator; production passes none.
+module.exports = function buildMyPasskeysRouter({
+  store = require('../passkeys'),
+  webauthn = null,
+  requireBuilder = auth.requireBuilder,
+} = {}) {
+  const router = express.Router();
+  const lib = () => webauthn || require('@simplewebauthn/server');
+
+  // GET /api/bongos/me/passkeys — the caller's registered cards.
+  // rank: any-builder (own identity only).
+  router.get('/me/passkeys', requireBuilder, async (req, res) => {
+    try {
+      const rows = await store.listCredentials(req.builder.id);
+      res.json({ passkeys: rows.map(presentCard) });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'GET /me/passkeys failed');
+      res.fail('list_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /api/bongos/me/passkeys/browser.js — the vetted @simplewebauthn/browser
+  // bundle, served same-origin so the page needs no CDN and no build step.
+  // rank: any-builder (own identity only) — a vendored static file at a fixed
+  // path, served only to a signed-in builder like the rest of /me.
+  router.get('/me/passkeys/browser.js', requireBuilder, (_req, res) => {
+    const file = browserBundleFile();
+    if (!file) {
+      log.error('passkeys browser bundle missing');
+      return res.fail('bundle_missing', { status: 500, message: 'internal error' });
+    }
+    res.type('application/javascript').set('Cache-Control', 'public, max-age=3600').sendFile(file, (err) => {
+      if (err && !res.headersSent) res.fail('bundle_missing', { status: 500, message: 'internal error' });
+    });
+  });
+
+  // POST /api/bongos/me/passkeys/register/options — start adding a card.
+  // rank: any-builder (own identity only).
+  router.post('/me/passkeys/register/options', requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {})) return;
+    try {
+      const rp = relyingParty(req);
+      if (!rp) return res.fail('passkeys_not_configured', { status: 503, message: 'security cards are not configured on this site yet' });
+      const { rpID, rpName } = rp;
+      const existing = await store.listCredentials(req.builder.id);
+      if (existing.length >= MAX_CARDS_PER_BUILDER) {
+        return res.fail('too_many_cards', { status: 409, message: `at most ${MAX_CARDS_PER_BUILDER} cards per account — remove one first` });
+      }
+      const handle = await store.getOrCreateUserHandle(req.builder.id);
+      const { challenge } = await store.createChallenge({ purpose: 'register', builderId: req.builder.id });
+      const options = await lib().generateRegistrationOptions({
+        rpName,
+        rpID,
+        userName: req.builder.github_login || req.builder.display_name || String(req.builder.id),
+        userDisplayName: req.builder.display_name || req.builder.github_login || undefined,
+        userID: Buffer.from(handle, 'base64url'),
+        challenge: Buffer.from(challenge, 'base64url'),
+        attestationType: 'none',
+        excludeCredentials: existing.map((c) => ({ id: c.credential_id, transports: c.transports })),
+        authenticatorSelection: { residentKey: 'preferred', userVerification: 'required' },
+      });
+      res.json({ options });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'register/options failed');
+      res.fail('options_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /api/bongos/me/passkeys/register/verify — finish adding a card.
+  // Body: { response, nickname? } where response is the browser's attestation.
+  // rank: any-builder (own identity only).
+  router.post('/me/passkeys/register/verify', requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, { response: {}, nickname: {} })) return;
+    const response = req.body && req.body.response;
+    if (!response || typeof response !== 'object') {
+      return res.fail('bad_response', { status: 400, message: 'response is required' });
+    }
+    const nick = cleanNickname(req.body.nickname);
+    if (nick.error) return res.fail('bad_nickname', { status: 400, message: nick.error });
+    try {
+      const rp = relyingParty(req);
+      if (!rp) return res.fail('passkeys_not_configured', { status: 503, message: 'security cards are not configured on this site yet' });
+      const { origin, rpID } = rp;
+      let verification;
+      try {
+        verification = await lib().verifyRegistrationResponse({
+          response,
+          // The library hands back the challenge the card signed. Consuming it here
+          // is what makes it single-use and bound to THIS builder and purpose.
+          expectedChallenge: async (c) => !!(await store.consumeChallenge(c, { expectPurpose: 'register', expectBuilderId: req.builder.id })),
+          expectedOrigin: origin,
+          expectedRPID: rpID,
+          requireUserVerification: true,
+        });
+      } catch (err) {
+        log.info({ err: err && err.message }, 'register/verify refused');
+        return res.fail('verification_failed', { status: 400, message: 'the card could not be verified' });
+      }
+      if (!verification.verified || !verification.registrationInfo) {
+        return res.fail('verification_failed', { status: 400, message: 'the card could not be verified' });
+      }
+      const { credential, aaguid } = verification.registrationInfo;
+      // Same answer whoever holds it: a global lookup must not reveal that a card
+      // belongs to another account.
+      if (await store.getCredentialById(credential.id)) {
+        return res.fail('already_registered', { status: 409, message: 'that card cannot be registered' });
+      }
+      // The cap is enforced here too: a challenge minted before a removal must not
+      // let a builder end up over it.
+      if ((await store.listCredentials(req.builder.id)).length >= MAX_CARDS_PER_BUILDER) {
+        return res.fail('too_many_cards', { status: 409, message: `at most ${MAX_CARDS_PER_BUILDER} cards per account — remove one first` });
+      }
+      await store.addCredential({
+        builderId: req.builder.id,
+        credentialId: credential.id,
+        publicKey: credential.publicKey,
+        signCount: credential.counter,
+        transports: credential.transports || response.response?.transports || [],
+        aaguid: aaguid || null,
+        nickname: nick.value,
+      });
+      res.json({ ok: true, credential_id: credential.id });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'register/verify failed');
+      res.fail('register_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /api/bongos/me/passkeys/rename — Body: { credential_id, nickname }.
+  // rank: any-builder (own identity only) — the WHERE clause is the boundary.
+  router.post('/me/passkeys/rename', requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, { credential_id: {}, nickname: {} })) return;
+    const id = req.body && req.body.credential_id;
+    if (typeof id !== 'string' || !CREDENTIAL_ID_RE.test(id)) {
+      return res.fail('bad_credential_id', { status: 400, message: 'credential_id must come from GET /me/passkeys' });
+    }
+    if (req.body.nickname === undefined) return res.fail('bad_nickname', { status: 400, message: 'nickname is required (send an empty string to clear it)' });
+    const nick = cleanNickname(req.body.nickname);
+    if (nick.error) return res.fail('bad_nickname', { status: 400, message: nick.error });
+    try {
+      const ok = await store.renameCredential(req.builder.id, id, nick.value);
+      if (!ok) return res.fail('not_found', { status: 404, message: 'no such card on your account' });
+      res.json({ ok: true });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'rename failed');
+      res.fail('rename_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /api/bongos/me/passkeys/remove — Body: { credential_id }.
+  // rank: any-builder (own identity only) — the WHERE clause is the boundary.
+  router.post('/me/passkeys/remove', requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, { credential_id: {} })) return;
+    const id = req.body && req.body.credential_id;
+    if (typeof id !== 'string' || !CREDENTIAL_ID_RE.test(id)) {
+      return res.fail('bad_credential_id', { status: 400, message: 'credential_id must come from GET /me/passkeys' });
+    }
+    try {
+      const ok = await store.removeCredential(req.builder.id, id);
+      if (!ok) return res.fail('not_found', { status: 404, message: 'no such card on your account' });
+      res.json({ ok: true });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'remove failed');
+      res.fail('remove_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};