@bongos/core 1.24.96 → 1.25.2

package/modules/economy/tests/processor_stripe.mjs

@@ -0,0 +1,135 @@
+// modules/economy/tests/processor_stripe.mjs — task 1005040. DB-free, no network: the Stripe
+// Connect test-mode adapter against a fake fetch. Run: node modules/economy/tests/processor_stripe.mjs
+import { createRequire } from 'node:module';
+import { strict as assert } from 'node:assert';
+import crypto from 'node:crypto';
+const require = createRequire(import.meta.url);
+const { createStripeProcessor, fromEnv } = require('../processor-stripe.js');
+
+let pass = 0;
+const ok = (c, m) => { assert.ok(c, m); pass++; console.log(`  ok - ${m}`); };
+// Fake keys are assembled at run time so no key-shaped literal sits in the repo.
+const FAKE = 'placeholder12345678';
+const KEY = ['sk', 'test', FAKE].join('_');
+const LIVE = ['sk', 'live', FAKE].join('_');
+const RESTRICTED = ['rk', 'test', FAKE].join('_');
+const PROJ = 'acct_project0001';
+const ME = 'acct_member00001';
+
+const calls = [];
+const fake = (answer) => async (url, init) => {
+  calls.push({ url, ...init });
+  const r = await answer(url, init);
+  return { ok: (r.status || 200) < 400, status: r.status || 200, json: async () => r.body };
+};
+const make = (answer, extra = {}) => createStripeProcessor({ secretKey: KEY, projectAccount: PROJ, projectKey: 'p1', fetchImpl: fake(answer), memberAccountFor: async (id) => (id === '5' ? ME : null), ...extra });
+const err = async (fn) => { try { await fn(); } catch (e) { return e; } return null; };
+
+// ── test mode only ───────────────────────────────────────────────────────
+ok((await err(() => createStripeProcessor({ secretKey: LIVE }))).code === 'test_key_only', 'a live key is refused');
+ok((await err(() => createStripeProcessor({ secretKey: RESTRICTED }))).code === 'test_key_only', 'only test secret keys are accepted');
+ok(fromEnv({}) === null, 'no key in the environment: no adapter (flows hold no_processor)');
+ok(fromEnv({ STRIPE_SECRET_KEY: KEY, STRIPE_PROJECT_ACCOUNT: PROJ }).testMode === true, 'built from the environment, flagged test mode');
+
+// ── payout: key, account header, paid flag, refused mapping ──────────────
+let p = make(() => ({ body: { id: 'po_1', status: 'in_transit' } }));
+let out = await p.memberPayout({ idempotencyKey: 'bongos-cashout-7-1', amountCents: 2500, currency: 'USD', account: ME });
+ok(out.ref === 'po_1' && out.paid === false, 'payout returns the reference, not yet paid');
+const c = calls.at(-1);
+ok(c.url.endsWith('/v1/payouts') && c.headers['Idempotency-Key'] === 'bongos-cashout-7-1', 'payout sends the caller idempotency key');
+ok(c.headers['Stripe-Account'] === ME && c.body.includes('amount=2500') && c.body.includes('currency=usd'), "payout acts on the person's account for the exact amount");
+p = make(() => ({ body: { id: 'po_2', status: 'paid' } }));
+ok((await p.memberPayout({ idempotencyKey: 'k', amountCents: 1000, currency: 'USD', account: ME })).paid === true, 'a payout Stripe reports paid is paid');
+p = make(() => ({ status: 400, body: { error: { code: 'balance_insufficient', message: 'no funds' } } }));
+let e = await err(() => p.memberPayout({ idempotencyKey: 'k', amountCents: 1000, currency: 'USD', account: ME }));
+ok(e.refused === true && e.code === 'balance_insufficient', 'a 4xx that created nothing is refused');
+for (const status of [500, 409, 429, 408]) {
+  p = make(() => ({ status, body: { error: { message: 'x' } } }));
+  e = await err(() => p.memberPayout({ idempotencyKey: 'k', amountCents: 1000, currency: 'USD', account: ME }));
+  ok(e && e.refused === false, `a ${status} may have paid, so it is not refused (retry on the same key)`);
+}
+p = make(() => { throw new Error('socket hang up'); });
+e = await err(() => p.memberPayout({ idempotencyKey: 'k', amountCents: 1000, currency: 'USD', account: ME }));
+ok(e.refused === false && e.code === 'network', 'a network failure is not refused');
+p = make(() => ({ body: {} }));
+ok((await err(() => p.memberPayout({ idempotencyKey: 'k', amountCents: 10.5, currency: 'USD', account: ME }))).refused === true, 'a fractional amount is refused before any call');
+ok((await err(() => p.memberPayout({ idempotencyKey: 'k', amountCents: 1000, currency: 'EUR', account: ME }))).code === 'currency_not_supported', 'only dollars');
+ok((await err(() => p.memberPayout({ idempotencyKey: 'k', amountCents: 1000, currency: 'USD', account: 'nope' }))).code === 'bad_account', 'a malformed account is refused');
+
+// guardian routing, unreadable replies, project key, cache, urls
+p = make(() => ({ body: { id: 'po_x' } }));
+const n0 = calls.length;
+e = await err(() => p.memberPayout({ idempotencyKey: 'k', amountCents: 1000, currency: 'USD', account: ME, payTo: { guardian_id: '2', guardian_account: 'acct_guardian001' } }));
+ok(e.code === 'guardian_payout_unsupported' && e.refused === true && calls.length === n0, 'a guardian-routed payout is refused and nothing is sent');
+p = make(() => ({ status: 200, body: null }));
+e = await err(() => p.memberPayout({ idempotencyKey: 'k', amountCents: 1000, currency: 'USD', account: ME }));
+ok(e.code === 'bad_response' && e.refused === false, 'a 2xx with an unreadable body is not refused and says so');
+ok(fromEnv({ STRIPE_SECRET_KEY: KEY, STRIPE_PROJECT_ACCOUNT: PROJ }).confirmMemberAccount.length >= 0, 'built without a project key falls back to the project account');
+let reads = 0;
+p = make(() => { reads++; return { body: { available: [{ amount: 100, currency: 'usd' }], pending: [] } }; });
+await Promise.all([p.balanceMicro(), p.balanceMicro(), p.memberBalanceMicro(ME), p.memberBalanceMicro(ME)]);
+ok(reads === 2, 'identical balance reads at once share one Stripe call per account');
+p = make(() => ({ body: { url: 'https://x' } }), { allowedOrigin: 'https://proj.example' });
+ok((await err(() => p.onboardingLink({ accountRef: ME, returnUrl: 'https://evil.example/x', refreshUrl: 'https://proj.example/y' }))).code === 'bad_return_url', 'onboarding addresses outside the project origin are refused');
+ok((await p.onboardingLink({ accountRef: ME, returnUrl: 'https://proj.example/a', refreshUrl: 'https://proj.example/b' })).url === 'https://x', 'addresses on the project origin pass');
+
+// ── balances ─────────────────────────────────────────────────────────────
+p = make(() => ({ body: { available: [{ amount: 1000, currency: 'usd' }, { amount: 5, currency: 'eur' }], pending: [{ amount: 250, currency: 'usd' }] } }));
+ok(await p.balanceMicro() === 1250 * 10000, 'project balance is the dollar total in micro-dollars (other currencies ignored)');
+ok(calls.at(-1).headers['Stripe-Account'] === PROJ, 'read from the project account');
+ok(await p.memberBalanceMicro(ME) === 1250 * 10000 && calls.at(-1).headers['Stripe-Account'] === ME, 'member balance reads the member account');
+
+// ── account confirmation ─────────────────────────────────────────────────
+p = make(() => ({ body: { id: ME, metadata: { bongos_builder_id: '5', bongos_project: 'p1' } } }));
+ok(await p.confirmMemberAccount({ accountRef: ME, builderId: '5' }) === true, 'an account we opened for that person is confirmed');
+ok(await p.confirmMemberAccount({ accountRef: ME, builderId: '6' }) === false, 'not for someone else');
+p = make(() => ({ body: { id: ME, metadata: { bongos_builder_id: '5', bongos_project: 'other' } } }));
+ok(await p.confirmMemberAccount({ accountRef: ME, builderId: '5' }) === false, 'not an account another project opened');
+
+// ── transfers ────────────────────────────────────────────────────────────
+p = make(() => ({ body: { id: 'tr_1' } }));
+out = await p.transfer({ idempotencyKey: 'bongos-payout-9', amountCents: 700, currency: 'USD', builderId: '5', payTo: 'self' });
+ok(out.ref === 'tr_1' && calls.at(-1).headers['Stripe-Account'] === PROJ && calls.at(-1).body.includes(`destination=${ME}`), "a payout transfer goes project → the builder's own account");
+await p.transfer({ idempotencyKey: 'k2', amountCents: 700, currency: 'USD', builderId: '5', payTo: { guardian_id: '2', guardian_account: 'acct_guardian001' } });
+ok(calls.at(-1).body.includes('destination=acct_guardian001'), 'a 16-17 recipient is paid to the guardian');
+e = await err(() => p.transfer({ idempotencyKey: 'k3', amountCents: 700, currency: 'USD', builderId: '99', payTo: 'self' }));
+ok(e.code === 'no_member_account' && e.refused, 'no connected account: refused, nothing sent');
+const before = calls.length;
+await p.memberTransfer({ idempotencyKey: 'k4', amountCents: 300, currency: 'USD', fromAccount: ME, toAccount: null, toProject: true });
+ok(calls.length === before + 1 && calls.at(-1).body.includes(`destination=${PROJ}`) && calls.at(-1).headers['Stripe-Account'] === ME, 'funding the project: member account → project account');
+const bare = createStripeProcessor({ secretKey: KEY, fetchImpl: fake(() => ({ body: { id: 'x' } })) });
+ok((await err(() => bare.balanceMicro())).code === 'no_project_account', 'no project account configured: refused');
+
+// ── sale ─────────────────────────────────────────────────────────────────
+p = make(() => ({ body: { id: 'pi_1', status: 'succeeded', amount: 1000, currency: 'usd', application_fee_amount: 100, metadata: { module_key: 'cool-mod' } } }));
+const sale = await p.readSale({ ref: 'pi_1' });
+ok(sale.moduleKey === 'cool-mod' && sale.priceCents === 1000 && sale.platformFeeCents === 100 && sale.currency === 'USD', 'a sale is read from Stripe, in the shape the module-share code checks');
+p = make(() => ({ body: { id: 'pi_2', status: 'requires_payment_method', amount: 1000, currency: 'usd' } }));
+ok((await err(() => p.readSale({ ref: 'pi_2' }))).code === 'sale_not_paid', 'an unpaid sale is refused');
+
+// ── movements, with paging ───────────────────────────────────────────────
+let page = 0;
+p = make(() => (++page === 1
+  ? { body: { has_more: true, data: [{ id: 'txn_1', source: 'tr_1', amount: -700, currency: 'usd', created: 1_700_000_000 }] } }
+  : { body: { has_more: false, data: [{ id: 'txn_2', source: 'po_1', amount: 2500, currency: 'usd', created: 1_700_000_100 }] } }));
+const mv = await p.listMovements({ since: new Date(1_699_000_000_000), until: new Date(1_701_000_000_000) });
+ok(mv.length === 2 && mv[0].ref === 'tr_1' && mv[0].amountMicro === 700 * 10000 && mv[1].ref === 'po_1', 'movements are paged and listed by object id, unsigned, in micro-dollars');
+ok(calls.at(-1).url.includes('starting_after=txn_1'), 'the second page continues after the first');
+
+// ── webhook ──────────────────────────────────────────────────────────────
+const SECRET = 'webhook-test-secret';
+const hook = createStripeProcessor({ secretKey: KEY, webhookSecret: SECRET, fetchImpl: fake(() => ({})), now: () => 1_700_000_000_000 });
+const body = JSON.stringify({ type: 'payout.failed', data: { object: { id: 'po_9', failure_message: 'account closed' } } });
+const sign = (t, b) => `t=${t},v1=${crypto.createHmac('sha256', SECRET).update(`${t}.${b}`).digest('hex')}`;
+const ev = hook.verifyWebhook(body, sign(1_700_000_000, body));
+ok(ev.type === 'payout.failed', 'a correctly signed webhook is accepted');
+const news = hook.payoutNews(ev);
+ok(news.outcome === 'returned' && news.ref === 'po_9' && news.reason === 'account closed', "payout.failed becomes a return with the bank's reason");
+ok(hook.payoutNews({ type: 'payout.paid', data: { object: { id: 'po_9' } } }).outcome === 'paid', 'payout.paid becomes paid');
+ok(hook.payoutNews({ type: 'charge.succeeded', data: { object: { id: 'ch_1' } } }).handled === false, 'other events are ignored');
+ok((await err(() => hook.verifyWebhook(`${body} `, sign(1_700_000_000, body)))).code === 'bad_signature', 'a tampered body is refused');
+ok((await err(() => hook.verifyWebhook(body, sign(1_699_990_000, body)))).code === 'bad_signature', 'a stale timestamp is refused');
+ok((await err(() => hook.verifyWebhook(body, sign(1_700_000_200, body)))).code === 'bad_signature', 'a timestamp from the future is refused');
+ok((await err(() => hook.verifyWebhook(body, 't=1700000000,v1=abcd'))).code === 'bad_signature', 'a wrong signature is refused');
+
+console.log(`\n${pass} passed`);

package/modules/government/routes/government.js

@@ -1344,7 +1344,7 @@ module.exports = function buildGovernmentRouter() {
   // seat while it is unseated — may (403 not_the_holder). Only an open goal.
   //
   // Body: { budget_usd: number | null }  → 200 { ok, pot | removed }
-  router.put('/government/treasury/pots/:goalId', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+  router.put('/government/treasury/pots/:goalId', api.requireBuilder, api.requirePermission('board.vote.cast'), api.requireCardStepUp, async (req, res) => {
     const goalId = parseId(req, res, { param: 'goalId', code: 'bad_goal_id', positiveInt: true });
     if (goalId === null) return;
     if (validateOrRespond(req, res, { budget_usd: {} })) return; // a number of dollars, or null to take the pot away; parsed below
@@ -1375,7 +1375,7 @@ module.exports = function buildGovernmentRouter() {
   // stops nothing: with no spend limit, work runs on and the overspend is debt.
   //
   // Body: { key: 'lend' | 'half' | 'no' }  → 200 { ok, borrow }
-  router.post('/government/treasury/borrows/:borrowId/answer', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+  router.post('/government/treasury/borrows/:borrowId/answer', api.requireBuilder, api.requirePermission('board.vote.cast'), api.requireCardStepUp, async (req, res) => {
     const borrowId = parseId(req, res, { param: 'borrowId', code: 'bad_borrow_id', positiveInt: true });
     if (borrowId === null) return;
     if (validateOrRespond(req, res, { key: { required: true, type: 'string', maxLength: 16 } })) return;

package/modules/hall-ui/public/visor.js

@@ -11,9 +11,10 @@
 //     the character's colour; task 1005218), your character's name and your credits
 //     (builders.total_credits — credits only, never a payout; the spec's "does not exist").
 //     Centre: your character's main action, the one accent button, with its key. Right: the
-//     quiet key hints, no boxes: your other actions, "Actions" (key A), which opens the
-//     sheet (your character's actions, then the keys of the place you are in, then Options
-//     on Escape), and Options itself.
+//     quiet key hints, no boxes: your other actions and "Actions" (key A), which opens the
+//     sheet (your character's actions, then the keys of the place you are in, then Options on
+//     a key of its own; Escape closes it). Options is only in the sheet (task 1005248).
+//   - every key comes from resolveKeys: one owner per key, never two (task 1005248).
 //
 // The rules it keeps (ADR 0399):
 //   - one overlay, #visor, with pointer-events: none; only its controls take a pointer, so a
@@ -59,6 +60,11 @@
     ],
   };
   var SHEET_KEY = 'a';
+  var CLOSE_KEY = 'esc';   // shown once: the sheet's Close (Escape)
+  var OPTIONS = { id: 'options', label: 'Options', key: 'o', href: '/settings' };
+  // Keys a scene binds on its own page (the sky's L 0 / ?, the gallery's F, the palette's K).
+  // A moved key never lands on one of them; a scene that declares one keeps it.
+  var AVOID = ['l', '0', '/', '?', 'f', 'k', '+', '-', '='];
   var NAMES = { artisan: 'Artisan', artist: 'Artist', patron: 'Patron' };
 
   function esc(v) { return window.OTB && window.OTB.escapeHtml ? window.OTB.escapeHtml(v) : String(v == null ? '' : v).replace(/[^\w .,:'-]/g, ''); }
@@ -151,6 +157,42 @@
     render();
   }
 
+  // ---------- the keys: one resolver, so no key ever means two things (task 1005248) ----------
+  // Every key the visor shows or binds comes from here, and here hands each key out once.
+  // A key in ACTIONS or a scene's registration is a RECOMMENDATION: when it is already taken
+  // the action moves to the next free letter of its own name, then of the alphabet, and with
+  // none free it shows and binds no key at all. Never two owners. In order of who keeps a key:
+  //   1. the visor's own: A (Actions) and Escape (Close, while the sheet is open);
+  //   2. the keys a scene binds itself (an action without `bind`, and the `keys` lines): the
+  //      visor cannot move a key it does not bind, so a second claim on one shows no key;
+  //   3. the character's actions, in order; 4. the scene's `bind` actions; 5. Options.
+  function norm(k) { return k ? String(k).toLowerCase() : ''; }
+  function resolveKeys(id) {
+    var taken = {};
+    function claim(k, who) { if (!k || taken[k]) return ''; taken[k] = who; return k; }
+    function free(pref, label, who) {
+      var got = claim(norm(pref), who);
+      if (got || !pref) return got;
+      var pool = String(label || '').toLowerCase().replace(/[^a-z]/g, '') + 'abcdefghijklmnopqrstuvwxyz';
+      for (var i = 0; i < pool.length; i++) if (AVOID.indexOf(pool[i]) < 0 && claim(pool[i], who)) return pool[i];
+      return '';
+    }
+    claim(SHEET_KEY, 'sheet');
+    claim(CLOSE_KEY, 'close');
+    var sa = scene ? scene.actions : [], sk = scene ? scene.keys : [];
+    var place = sa.map(function () { return ''; });
+    sa.forEach(function (a, i) { if (!a.bind) place[i] = claim(norm(a.key), 'place:' + i); });
+    var lines = sk.map(function (k, i) { return claim(norm(k.key), 'line:' + i); });
+    var acts = actionsFor(id).map(function (a) {
+      var c = {}; for (var p in a) c[p] = a[p];
+      c.key = free(a.key, a.label, a.id);
+      return c;
+    });
+    sa.forEach(function (a, i) { if (a.bind) place[i] = free(a.key, a.label, 'place:' + i); });
+    var opts = { id: OPTIONS.id, label: OPTIONS.label, href: OPTIONS.href, key: free(OPTIONS.key, OPTIONS.label, OPTIONS.id) };
+    return { actions: acts, place: place, lines: lines, options: opts, taken: taken };
+  }
+
   // ---------- what the scene has picked (task 1005243) ----------
   // A scene that picks something (Home's tower) hands the visor a small card about it:
   // a title, one status, a few lines, and at most one action. The action becomes the
@@ -227,7 +269,7 @@
       svgOpen('visor__notch', '0 0 12 9') + twice('<path class="visor__line" d="M0 0l6 9l6 -9"/>') + '</svg>' +
       svgOpen('visor__sight', '0 0 24 24') + twice('<circle class="visor__line" cx="12" cy="12" r="11"/>') + '<circle class="visor__dot" cx="12" cy="12" r="2"/></svg>';
   }
-  function keyHtml(k) { k = String(k); return '<kbd class="visor__key">' + esc(k.length === 1 ? k.toUpperCase() : k) + '</kbd>'; }
+  function keyHtml(k) { k = String(k || ''); if (!k) return ''; if (k === CLOSE_KEY) k = 'Esc'; return '<kbd class="visor__key">' + esc(k.length === 1 ? k.toUpperCase() : k) + '</kbd>'; }
   // The count and its unit are two spans, so the number can be white and the word ice; the
   // text between them is still creditsText's, word for word.
   function creditsHtml(n) {
@@ -240,14 +282,14 @@
     return '<a class="visor__hint" data-visor-act="' + esc(a.id) + '" ' + actionAttrs(a) + '>' + keyHtml(a.key) + '<span>' + esc(a.label) + '</span></a>';
   }
   // The scene's lead action, as the first quiet hint (task 1005209).
-  function placeHintHtml(a, i) {
-    return '<button class="visor__hint visor__hint--place" type="button" data-visor-scene="' + i + '">' + (a.key ? keyHtml(a.key) : '') + '<span>' + esc(a.label) + '</span></button>';
+  function placeHintHtml(a, i, key) {
+    return '<button class="visor__hint visor__hint--place" type="button" data-visor-scene="' + i + '">' + keyHtml(key) + '<span>' + esc(a.label) + '</span></button>';
   }
   function actionAttrs(a) {
     return a.href ? 'href="' + esc(hallHref(a.href)) + '"' : 'href="#" role="button"';
   }
   function glassHtml(id) {
-    var acts = actionsFor(id), main = acts[0], C = craft();
+    var keys = resolveKeys(id), acts = keys.actions, main = acts[0], C = craft();
     // Your picture on the glass is you wearing the visor (task 1005218); an older craft-mode
     // without that picture still hands over the whole figure.
     var sprite = C && typeof C.portraitSrc === 'function' ? C.portraitSrc(id) : (C && typeof C.spriteSrc === 'function' ? C.spriteSrc(id) : '');
@@ -263,10 +305,9 @@
           '<span class="visor__credits" data-visor-credits>' + creditsHtml(n) + '</span></span>' +
         '</div>' +
         mainHtml(main) +
-        '<div class="visor__hints">' + scene.actions.map(function (a, i) { return a.lead ? placeHintHtml(a, i) : ''; }).join('') + acts.slice(1).map(hintHtml).join('') +
+        '<div class="visor__hints">' + scene.actions.map(function (a, i) { return a.lead ? placeHintHtml(a, i, keys.place[i]) : ''; }).join('') + acts.slice(1).map(hintHtml).join('') +
           '<button class="visor__hint visor__hint--sheet" type="button" data-visor-sheet aria-expanded="false" aria-controls="visor-sheet">' +
             '<span class="visor__dots" aria-hidden="true"></span>' + keyHtml(SHEET_KEY) + '<span>Actions</span></button>' +
-          '<a class="visor__hint visor__hint--options" href="' + esc(hallHref('/settings')) + '">' + keyHtml('Esc') + '<span>Options</span></a>' +
         '</div>' +
       '</div>';
   }
@@ -280,20 +321,22 @@
       '<p class="visor__progress-words"><span class="sr-only">' + esc(said) + '</span>' +
       '<span aria-hidden="true">' + esc(progress.id) + ' · ' + progress.pct + '%</span></p></div>';
   }
+  // Options lives only in here (the owner, 2026-11-12), on a key of its own: Escape is Close.
   function sheetHtml(id) {
-    var rows = actionsFor(id).map(function (a) {
+    var keys = resolveKeys(id);
+    var rows = keys.actions.map(function (a) {
       return '<li><a class="visor__row" data-visor-act="' + esc(a.id) + '" ' + actionAttrs(a) + '><span>' + esc(a.label) + '</span>' + keyHtml(a.key) + '</a></li>';
     }).join('');
     var place = scene.actions.map(function (a, i) {
-      return '<li><button class="visor__row" type="button" data-visor-scene="' + i + '"><span>' + esc(a.label) + '</span>' + (a.key ? keyHtml(a.key) : '') + '</button></li>';
-    }).concat(scene.keys.map(function (k) {
-      return '<li><span class="visor__row visor__row--hint"><span>' + esc(k.label) + '</span>' + keyHtml(k.key) + '</span></li>';
+      return '<li><button class="visor__row" type="button" data-visor-scene="' + i + '"><span>' + esc(a.label) + '</span>' + keyHtml(keys.place[i]) + '</button></li>';
+    }).concat(scene.keys.map(function (k, i) {
+      return '<li><span class="visor__row visor__row--hint"><span>' + esc(k.label) + '</span>' + keyHtml(keys.lines[i]) + '</span></li>';
     })).join('');
     return '<div class="visor__sheet-head"><h2 class="visor__sheet-title" id="visor-sheet-title">Actions</h2>' +
-        '<button class="visor__close" type="button" data-visor-close aria-label="Close actions">' + keyHtml('Esc') + '</button></div>' +
+        '<button class="visor__close" type="button" data-visor-close aria-label="Close actions">' + keyHtml(CLOSE_KEY) + '</button></div>' +
       '<p class="visor__cap">' + esc(NAMES[id]) + '</p><ul class="visor__rows">' + rows + '</ul>' +
       (place ? '<p class="visor__cap">This place</p><ul class="visor__rows">' + place + '</ul>' : '') +
-      '<ul class="visor__rows"><li><a class="visor__row" href="' + esc(hallHref('/settings')) + '"><span>Options</span>' + keyHtml('Esc') + '</a></li></ul>';
+      '<ul class="visor__rows"><li><a class="visor__row" data-visor-act="options" href="' + esc(hallHref(keys.options.href)) + '"><span>' + esc(keys.options.label) + '</span>' + keyHtml(keys.options.key) + '</a></li></ul>';
   }
   function shown() { return !!(root && !root.hidden); }
   function render() {
@@ -375,10 +418,12 @@
       if (C && typeof C.openTool === 'function') C.openTool(a.tool);
       return;
     }
+    // Options opens the game's options window over the place when it can (shell-game.js)
+    if (a.id === OPTIONS.id && window.OTBOptionsOverlay && typeof window.OTBOptionsOverlay.open === 'function') { window.OTBOptionsOverlay.open(); return; }
     if (a.href) window.location.assign(hallHref(a.href));
   }
   function find(id) {
-    var acts = actionsFor(character());
+    var acts = resolveKeys(character()).actions;
     for (var i = 0; i < acts.length; i++) if (acts[i].id === id) return acts[i];
     return null;
   }
@@ -415,11 +460,12 @@
     if (!e || e.defaultPrevented || e.ctrlKey || e.metaKey || e.altKey || typeof e.key !== 'string' || e.key.length !== 1) return null;
     var k = e.key.toLowerCase();
     if (k === SHEET_KEY) return 'sheet';
-    var acts = actionsFor(id);
-    for (var i = 0; i < acts.length; i++) if (acts[i].key === k) return acts[i];
-    // then the keys the visor binds for the place (task 1005209); the character's win a clash
+    // the resolver gave each key one owner, so the first match is the only one
+    var keys = resolveKeys(id);
+    for (var i = 0; i < keys.actions.length; i++) if (keys.actions[i].key === k) return keys.actions[i];
     var own = scene ? scene.actions : [];
-    for (var j = 0; j < own.length; j++) if (own[j].bind && own[j].key === k) return own[j];
+    for (var j = 0; j < own.length; j++) if (own[j].bind && keys.place[j] === k) return own[j];
+    if (keys.options.key === k) return keys.options;
     return null;
   }
   // Bubble, on window: a scene or pop-up that used the key has called preventDefault by now.
@@ -460,6 +506,7 @@
     ACTIONS: ACTIONS,
     actionsFor: actionsFor,
     keyFor: keyFor,
+    resolveKeys: resolveKeys,
     creditsText: creditsText,
     character: character,
     pickVersion: pickVersion,

package/modules/hall-ui/records/visor.md

@@ -6,6 +6,13 @@ Covers: `visor.js` + `visor.css`, loaded on Home, `/city`, `/goal-map` and `/thi
 
 The visor is the control and the scene is the view: every main call to action in game mode is on the glass (the accent button, the key hints, the Actions sheet), and a scene carries none of its own. A scene that has something to do registers it with `OTBVisor.scene({ actions, keys })`. ADR 0403 §3 lists the scenes that do not keep it yet; the Governor City keeps it since task 1005209 the sky since task 1005210, and Home's gallery since task 1005211 (below).
 
+## One owner per key (task 1005248, owner 2026-11-12)
+
+- **The bug.** The Artist saw Esc twice: "Options" on the glass, then in the Actions sheet both Close and the Options row said Esc.
+- **The rule.** A key in `ACTIONS` or a scene's registration is a recommendation. `resolveKeys(id)` in `visor.js` hands every key out once, and the glass, the sheet and `keyFor` all read it; nothing else names a key. Who keeps a key, in order: the visor's own (A Actions, Escape Close); the keys a scene binds itself (an action without `bind`, the `keys` lines), because the visor cannot move a key it does not bind, so a second claim on one shows no key; the character's actions; the scene's `bind` actions; Options. A later claimant moves to the next free letter of its own name, then of the alphabet, never onto a key a scene binds on its page (`AVOID`: L 0 / ? F K + - =); with none free it has no key.
+- **Options is only in the sheet** (the owner likes it there), on O, or its next free letter (the Patron's O is the Board room, so P). Pressing it opens the options window over the place, like a click. Escape on the glass is the sheet's Close only. The shell's "last Escape opens the options menu" (`shell-game.js`, ADR 0399 §2.4) is not a visor key and is unchanged.
+- **Tests:** `tests/hall_visor.mjs` proves no shared key for every character over the sky, the city and Home, and over a hostile scene that claims A, Escape, a character key and one key twice.
+
 ## A place's own buttons on the glass (task 1005209, the Governor City first)
 
 - **The scene contract grew two flags.** A scene action's `key` is still a key the scene binds itself, shown beside it in the sheet. With `bind: true` the visor binds that key instead, after the character's keys (a clash goes to the character), for a scene button that had no key of its own. With `lead: true` the action is also the first quiet key hint on the glass (`.visor__hint--place`). Every scene action is still a row under "This place" in the sheet.

package/modules/render-deploy/routes/act.js

@@ -26,7 +26,7 @@ const log = api.logger('render-deploy');
 module.exports = function buildRenderDeployActRouter({ makeClient = defaultMakeClient, pool } = {}) {
   const router = express.Router();
 
-  router.post('/render-deploy/act', api.requireBuilder, api.requirePermission('core.pin.move'), api.requireActAlone('release'), async (req, res) => {
+  router.post('/render-deploy/act', api.requireBuilder, api.requirePermission('core.pin.move'), api.requireCardStepUp, api.requireActAlone('release'), async (req, res) => {
     const db = pool || api.pool;
     // Shape only, and strict: an undeclared field is refused. `confirm` and `expectLiveDeployId`
     // are left to the checks below so each gets its own plain refusal rather than a schema one.

package/modules/render-deploy/routes/app.js

@@ -35,7 +35,7 @@ module.exports = function buildRenderDeployAppRouter({ makeClient = defaultMakeC
     }
   });
 
-  router.put('/render-deploy/app', api.requireBuilder, api.requirePermission('core.pin.move'), async (req, res) => {
+  router.put('/render-deploy/app', api.requireBuilder, api.requirePermission('core.pin.move'), api.requireCardStepUp, async (req, res) => {
     if (api.validateOrRespond(req, res, {
       ownerId: { type: 'string', maxLength: 80 },
       serviceId: { type: 'string', maxLength: 80 },

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.24.96",
+  "version": "1.25.2",
   "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

@@ -11689,5 +11689,22 @@
       "id": "1005243",
       "text": "In game mode, tap a goal tower on Home to send your Autobongos runner there with one visor button; the tower then shows your runner at work, and tapping it shows tasks done, tokens used, time left and a Recall button."
     }
+  ],
+  "1.25.0": [],
+  "1.25.1": [
+    {
+      "id": "1004747",
+      "text": "Sensitive actions (rank changes, deploys, signing sessions out, treasury payouts) can now require a tap of your hardware card within the last 10 minutes. Nobody is required to yet; an Archon switch comes next."
+    },
+    {
+      "id": "1005040",
+      "text": "Added the Stripe Connect test-mode payment adapter (economy.processor port). Every payout, cash-out, balance and ledger-check call now has a processor to talk to once a test key is set; nothing is live."
+    }
+  ],
+  "1.25.2": [
+    {
+      "id": "1005248",
+      "text": "In game mode, no two buttons on the visor share a hotkey any more, and Options now sits only inside the Actions menu with its own key."
+    }
   ]
 }

package/scripts/bongos/fitness.js

@@ -619,7 +619,7 @@ const KERNEL_FILES = [
   // by the doorway, so leaving it off reads as a kernel->non-kernel leak. It imports
   // only module-seams.js and logger.js (both on this roster) and reaches the
   // government module through its port, never by require.
-  'src/bongos/act-alone.js',
+  'src/bongos/act-alone.js', 'src/bongos/step-up.js', 'src/bongos/passkeys.js', // trust gate + its store (task 1004747, ADR 0382)
 ];
 
 // Kernel files exempt from the no-module-keys scan (Check 10) because naming a

package/scripts/bongos/government-walk.js

@@ -687,13 +687,13 @@ async function runWalk() {
 
   // The session: whoever the request says it is, from this project's people.
   const asHeader = 'x-walk-builder';
-  const sessionHeader = 'x-walk-session';
+  const sessionHeader = 'x-walk-session'; req('src/bongos/passkeys').stepUpStatus = async () => ({ required: false, fresh: false }); // task 1004747: no card is required in the walk
   const fakeBuilder = (r, res, nextFn) => {
     const b = store.builders.get(String(r.headers[asHeader] || ''));
     if (!b || b.status !== 'active') return res.status(401).json({ error: { code: 'not_signed_in' } });
     r.builder = { id: Number(b.id), rank: b.rank, github_login: b.github_login, display_name: b.display_name };
     // an AI session's CLI token, or a person in the hall (task 1004704's line)
-    r.gdsSession = { source: r.headers[sessionHeader] === 'cli' ? 'cli' : 'web' };
+    r.gdsSession = { source: r.headers[sessionHeader] === 'cli' ? 'cli' : 'web', session_id: '1' }; // session_id: the step-up gate (task 1004747) needs one
     return nextFn();
   };
   api.requireBuilder = fakeBuilder;

package/src/bongos/passkeys.js

@@ -15,6 +15,8 @@ const crypto = require('node:crypto');
 const CHALLENGE_TTL_SECONDS = 300;
 const MAX_CHALLENGE_TTL_SECONDS = 600;
 const PURPOSES = Object.freeze(['register', 'authenticate']);
+// How long one card tap keeps a session cleared for the protected actions (ADR 0382 D2).
+const STEP_UP_WINDOW_SECONDS = 600;
 
 function defaultPool() { return require('./pool').pool; }
 
@@ -146,7 +148,35 @@ async function renameCredential(builderId, credentialId, nickname, { pool = defa
   return r.rowCount > 0;
 }
 
+// Stamp the session that just passed a card check. Keyed on the builder as well, so a
+// session id that is not the caller's matches no row. Returns true when stamped.
+async function markSessionCardVerified(sessionId, builderId, { pool = defaultPool() } = {}) {
+  const r = await pool.query(
+    `UPDATE builder_sessions SET card_verified_at = now()
+      WHERE id = $1 AND builder_id = $2 AND revoked_at IS NULL`,
+    [sessionId, builderId],
+  );
+  return r.rowCount > 0;
+}
+
+// Where this session stands: is a card required of the builder, and is the session's
+// last tap inside the window? Read fresh from the DB on every call, never cached.
+async function stepUpStatus(sessionId, builderId, { pool = defaultPool(), windowSeconds = STEP_UP_WINDOW_SECONDS } = {}) {
+  const { rows } = await pool.query(
+    `SELECT b.require_card,
+            (s.card_verified_at IS NOT NULL
+               AND s.card_verified_at > now() - make_interval(secs => $3::int)) AS fresh
+       FROM builders b JOIN builder_sessions s ON s.builder_id = b.id
+      WHERE b.id = $1 AND s.id = $2`,
+    [builderId, sessionId, String(windowSeconds)],
+  );
+  const r = rows[0];
+  if (!r) return null;
+  return { required: r.require_card === true, fresh: r.fresh === true };
+}
+
 module.exports = {
+  STEP_UP_WINDOW_SECONDS, markSessionCardVerified, stepUpStatus,
   CHALLENGE_TTL_SECONDS, MAX_CHALLENGE_TTL_SECONDS, PURPOSES, clampTtlSeconds, counterAdvances,
   createChallenge, consumeChallenge, sweepExpiredChallenges,
   getOrCreateUserHandle, addCredential, getCredentialById, listCredentials, recordUse, removeCredential, renameCredential,

package/src/bongos/routes/auth.js

@@ -1418,7 +1418,7 @@ module.exports = function buildAuthRouter() {
   // rank: archon — kills an arbitrary session; can lock other builders out. Gate:
   // requirePermission('auth.session.revoke') — BV1.R104; the seeded rank-role makes
   // the permission and the old rank floor identical (ADR 0151).
-  router.post('/auth/revoke', auth.requireBuilder, auth.requirePermission('auth.session.revoke'), async (req, res) => {
+  router.post('/auth/revoke', auth.requireBuilder, auth.requirePermission('auth.session.revoke'), require('../step-up').requireCardStepUp, async (req, res) => {
     if (validateOrRespond(req, res, { session_id: {} })) return;  // bigint as number or string; validated below
     const sessionId = req.body && req.body.session_id;
     if (sessionId === undefined || sessionId === null) {
@@ -1446,7 +1446,7 @@ module.exports = function buildAuthRouter() {
   // rank: archon — same authority as PATCH /builders/:id/rank. Gate:
   // requirePermission('auth.session.revoke') — BV1.R104; the same atom /auth/revoke
   // gates on (ADR 0151).
-  router.post('/auth/revoke-all', auth.requireBuilder, auth.requirePermission('auth.session.revoke'), async (req, res) => {
+  router.post('/auth/revoke-all', auth.requireBuilder, auth.requirePermission('auth.session.revoke'), require('../step-up').requireCardStepUp, async (req, res) => {
     if (validateOrRespond(req, res, { builder_id: {} })) return;  // bigint as number or string; validated below
     const builderId = req.body && req.body.builder_id;
     if (builderId === undefined || builderId === null) {

package/src/bongos/routes/builders.js

@@ -24,6 +24,7 @@
 
 const express = require('express');
 const auth = require('../auth');
+const { requireCardStepUp } = require('../step-up');
 // WHO DECIDES AT TREASURY (task 1004657; ADR 0363 D5): the budget write refuses a
 // lone act while Treasury's decision-rules row names a sitting. A passed Treasury
 // matter sets the limit through setMonthlyBudget directly (the governor.matterAct
@@ -271,7 +272,7 @@ module.exports = function buildBuildersRouter() {
   // the permission and the old rank floor identical (ADR 0151). The atom is
   // `system: true`, so no CUSTOM role may ever be granted it — only the seeded archon
   // role holds it, which is exactly the meta-escalation wall ADR 0016 wants.
-  router.patch('/builders/:id/rank', auth.requireBuilder, auth.requirePermission('builder.rank.set'), async (req, res) => {
+  router.patch('/builders/:id/rank', auth.requireBuilder, auth.requirePermission('builder.rank.set'), requireCardStepUp, async (req, res) => {
     if (validateOrRespond(req, res, {
       rank: { required: true, type: 'string', maxLength: 32 },
     })) return;

package/src/bongos/routes/module-payouts.js

@@ -28,6 +28,8 @@ module.exports = function buildModulePayoutsRouter({
   requirePermission = auth.requirePermission,
 } = {}) {
   const router = express.Router();
+  // the processor adapter (modules/economy/processor-stripe.js, task 1005040) is a port, resolved per call
+  const proc = () => processor || require('../../module-seams').resolveOptional('economy.processor');
 
   function personal(req, res) {
     const p = store.personalSession(req);
@@ -74,7 +76,7 @@ module.exports = function buildModulePayoutsRouter({
     if (!actor) return;
     if (validateOrRespond(req, res, { processor_sale_ref: { required: true } })) return;
     try {
-      const out = await payouts.recordSale({ processorSaleRef: req.body.processor_sale_ref, actorId: actor.id }, { processor });
+      const out = await payouts.recordSale({ processorSaleRef: req.body.processor_sale_ref, actorId: actor.id }, { processor: proc() });
       res.status(out.already ? 200 : 201).json(out);
     } catch (err) { fail(res, err, 'POST /payouts/module-sales'); }
   });
@@ -104,7 +106,7 @@ module.exports = function buildModulePayoutsRouter({
     if (!actor) return;
     if (validateOrRespond(req, res, { approval_id: { required: true } })) return;
     try {
-      const out = await payouts.payShare({ shareId: req.params.id, approvalId: req.body.approval_id, actorId: actor.id }, { processor });
+      const out = await payouts.payShare({ shareId: req.params.id, approvalId: req.body.approval_id, actorId: actor.id }, { processor: proc() });
       res.set('Cache-Control', 'no-store');
       res.json(out);
     } catch (err) { fail(res, err, 'POST /payouts/module-shares/:id/pay'); }

package/src/bongos/routes/my-cash-outs.js

@@ -30,6 +30,8 @@ function buildMyCashOutsRouter({
   requireBuilder = auth.requireBuilder,
 } = {}) {
   const router = express.Router();
+  // the processor adapter (modules/economy/processor-stripe.js, task 1005040) is a port, resolved per call
+  const proc = () => processor || require('../../module-seams').resolveOptional('economy.processor');
 
   function personal(req, res) {
     const p = approvals.personalSession(req);
@@ -62,7 +64,7 @@ function buildMyCashOutsRouter({
   // GET /api/bongos/me/cash-outs — my withdrawals and where each stands.
   router.get('/me/cash-outs', requireBuilder, async (req, res) => {
     try {
-      const out = await cashOuts.listMyCashOuts(req.builder.id, { processor, limit: req.query.limit, log });
+      const out = await cashOuts.listMyCashOuts(req.builder.id, { processor: proc(), limit: req.query.limit, log });
       res.set('Cache-Control', 'no-store');
       res.json(out);
     } catch (err) { fault(res, err, 'GET /me/cash-outs'); }
@@ -76,7 +78,7 @@ function buildMyCashOutsRouter({
     try {
       const out = await cashOuts.requestCashOut({
         builderId: String(req.builder.id), actor, amountCents: req.body.amount_cents, instructionId: req.body.instruction_id,
-      }, { processor, log });
+      }, { processor: proc(), log });
       answer(res, out);
     } catch (err) { fault(res, err, 'POST /me/cash-outs'); }
   });
@@ -85,7 +87,7 @@ function buildMyCashOutsRouter({
   router.post('/me/cash-outs/:id/retry', requireBuilder, async (req, res) => {
     if (!personal(req, res)) return;
     try {
-      answer(res, await cashOuts.retryCashOut({ builderId: String(req.builder.id), cashOutId: req.params.id }, { processor }));
+      answer(res, await cashOuts.retryCashOut({ builderId: String(req.builder.id), cashOutId: req.params.id }, { processor: proc() }));
     } catch (err) { fault(res, err, 'POST /me/cash-outs/:id/retry'); }
   });