@bongos/core 1.24.96 → 1.25.1

package/modules/economy/processor-stripe.js

@@ -0,0 +1,292 @@
+'use strict';
+
+// modules/economy/processor-stripe.js — THE PAYMENT-RAIL ADAPTER: Stripe Connect, TEST MODE
+// ONLY (task 1005040, goal 1000092; ADR 0397 D1-D3, D5, D7).
+//
+// This is the one file that may name Stripe (ADR 0397: "a processor adapter module is the
+// only place that may name it"). Everything else calls the `economy.processor` port; a rail
+// change (the written J.P. Morgan fallback) replaces this file, not the product.
+//
+// TEST MODE ONLY. The factory refuses any key that is not `sk_test_…`, so no live key can be
+// stored or used by this build. Opening a live account is the owner's act and counsel's
+// items 1-4 (ADR 0385/0397) still gate it; lifting this guard is a separate, deliberate task.
+//
+// THE PORT (every method the callers already name; each is optional to the callers, all are
+// provided here):
+//   balanceMicro()                          the project's connected account balance
+//   memberBalanceMicro(accountRef)          one person's connected account balance
+//   confirmMemberAccount({accountRef, builderId})  true only for an account THIS project's
+//                                           connection opened for that person (metadata we set)
+//   memberTransfer({idempotencyKey, amountCents, currency, fromAccount, toAccount, toProject})
+//   transfer({idempotencyKey, amountCents, currency, builderId, payTo, taskId|moduleShareId})
+//                                           project account → the payee (self, or the guardian)
+//   memberPayout({idempotencyKey, amountCents, currency, account, payTo})
+//                                           connected account → the person's bank
+//   readSale({ref})                         a charge's own figures, never a screen's
+//   listMovements({since, until})           the project account's movements, by object id
+// Every money-moving call carries the caller's idempotency key as Stripe's `Idempotency-Key`,
+// so a retry gets back the object already made, never a second.
+//
+// ERROR MAPPING (ADR 0397 D7). An error carries `refused: true` ONLY when Stripe answered
+// 4xx (other than 408/409/429): it understood and created nothing. A timeout, a network
+// failure, a 5xx, a 409 or a 429 may have created the object, so they are not `refused` and
+// the caller retries on the same key.
+//
+// OPEN, UNVERIFIED AGAINST A LIVE TEST ACCOUNT (no Stripe account exists yet; the owner opens
+// it): account-to-account transfers (`memberTransfer`, `transfer`) are sent as a transfer made
+// "on behalf of" the paying connected account (the Stripe-Account header). If Stripe's account
+// type does not allow that, the call is refused and recorded `failed`; it never silently
+// moves money by another route.
+
+const crypto = require('node:crypto');
+
+const API = 'https://api.stripe.com';
+const MICRO_PER_CENT = 10_000;
+const CURRENCY = 'usd';
+const ACCOUNT_RE = /^acct_[A-Za-z0-9]{6,64}$/;
+const WEBHOOK_TOLERANCE_S = 300;
+
+class StripeError extends Error {
+  constructor(message, { code = 'stripe_error', status = null, refused = false } = {}) {
+    super(message);
+    this.name = 'StripeError';
+    this.code = code;
+    this.status = status;
+    this.refused = refused;
+  }
+}
+
+// Stripe takes form-encoded bodies, nested as a[b]=c.
+function encode(params, prefix = '') {
+  const out = [];
+  for (const [k, v] of Object.entries(params || {})) {
+    if (v === undefined || v === null) continue;
+    const key = prefix ? `${prefix}[${k}]` : k;
+    if (typeof v === 'object') out.push(...encode(v, key));
+    else out.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(v))}`);
+  }
+  return out;
+}
+
+function createStripeProcessor({
+  secretKey, projectAccount = null, projectKey = projectAccount || 'project', webhookSecret = null,
+  allowedOrigin = null,
+  fetchImpl = globalThis.fetch, memberAccountFor = null, timeoutMs = 12_000, now = () => Date.now(),
+} = {}) {
+  if (typeof secretKey !== 'string' || !/^sk_test_[A-Za-z0-9]{8,}$/.test(secretKey)) {
+    throw new StripeError('The Stripe key must be a test-mode secret key (sk_test_…); live keys are not accepted by this build.', { code: 'test_key_only' });
+  }
+  if (projectAccount !== null && !ACCOUNT_RE.test(projectAccount)) {
+    throw new StripeError('The project connected account must look like acct_….', { code: 'bad_project_account' });
+  }
+  if (typeof fetchImpl !== 'function') throw new StripeError('No fetch available.', { code: 'no_fetch' });
+
+  async function call(method, path, { params = null, account = null, idempotencyKey = null } = {}) {
+    const query = method === 'GET' && params ? `?${encode(params).join('&')}` : '';
+    const headers = { Authorization: `Bearer ${secretKey}` };
+    if (account) headers['Stripe-Account'] = account;
+    if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
+    let body;
+    if (method !== 'GET') { headers['Content-Type'] = 'application/x-www-form-urlencoded'; body = encode(params).join('&'); }
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), timeoutMs);
+    let res;
+    try {
+      res = await fetchImpl(`${API}${path}${query}`, { method, headers, body, signal: ctl.signal });
+    } catch (e) {
+      // may have reached Stripe: not refused
+      throw new StripeError(e && e.name === 'AbortError' ? 'Stripe did not answer in time' : `could not reach Stripe: ${e && e.message}`, { code: e && e.name === 'AbortError' ? 'timeout' : 'network' });
+    } finally { clearTimeout(timer); }
+    let json = null;
+    try { json = await res.json(); } catch { /* handled below */ }
+    if (res.ok && json) return json;
+    // a 2xx we cannot read may have created the object: not refused, retried on the same key
+    if (res.ok) throw new StripeError('Stripe answered but the reply could not be read', { code: 'bad_response', status: res.status });
+    const e = (json && json.error) || {};
+    const status = res.status;
+    const refused = status >= 400 && status < 500 && ![408, 409, 429].includes(status);
+    throw new StripeError(e.message || `Stripe answered ${status}`, { code: e.code || e.type || `http_${status}`, status, refused });
+  }
+
+  const microOf = (cents) => cents * MICRO_PER_CENT;
+  const checkMoney = ({ amountCents, currency }) => {
+    if (!Number.isSafeInteger(amountCents) || amountCents <= 0) throw new StripeError('amountCents must be a positive whole number.', { code: 'bad_amount', refused: true });
+    if (String(currency).toLowerCase() !== CURRENCY) throw new StripeError('Only US dollars are supported.', { code: 'currency_not_supported', refused: true });
+  };
+  const needProject = () => {
+    if (!projectAccount) throw new StripeError('No project connected account is configured (STRIPE_PROJECT_ACCOUNT).', { code: 'no_project_account', refused: true });
+    return projectAccount;
+  };
+
+  // Balance reads sit behind any-builder pages, so identical reads inside a few seconds share one
+  // Stripe call (and one in-flight request). A stale figure is harmless: Stripe refuses an overdraw.
+  const BALANCE_TTL_MS = 5000;
+  const balanceCache = new Map();
+  function balanceOf(account) {
+    const hit = balanceCache.get(account);
+    if (hit && now() - hit.at < BALANCE_TTL_MS) return hit.p;
+    const p = readBalance(account);
+    balanceCache.set(account, { at: now(), p });
+    p.catch(() => { if (balanceCache.get(account) && balanceCache.get(account).p === p) balanceCache.delete(account); });
+    return p;
+  }
+  // The figure counts available plus pending, so it matches what our record books on funding.
+  async function readBalance(account) {
+    const b = await call('GET', '/v1/balance', { account });
+    const avail = (b.available || []).filter((x) => x.currency === CURRENCY).reduce((s, x) => s + Number(x.amount), 0);
+    const pending = (b.pending || []).filter((x) => x.currency === CURRENCY).reduce((s, x) => s + Number(x.amount), 0);
+    return microOf(avail + pending);
+  }
+
+  // Resolve the account a payout/transfer lands in: the person's own, or the guardian's for a
+  // 16-17 recipient (payout-gates `pay_to`). Never taken from the request.
+  async function payeeAccount({ builderId, payTo }) {
+    if (payTo && typeof payTo === 'object') {
+      if (!ACCOUNT_RE.test(String(payTo.guardian_account || ''))) throw new StripeError('The guardian has no usable account.', { code: 'no_guardian_account', refused: true });
+      return payTo.guardian_account;
+    }
+    const acct = typeof memberAccountFor === 'function' ? await memberAccountFor(String(builderId)) : null;
+    if (!acct || !ACCOUNT_RE.test(acct)) throw new StripeError('The person has no connected account in this project.', { code: 'no_member_account', refused: true });
+    return acct;
+  }
+
+  const adapter = {
+    name: 'stripe-connect-test',
+    testMode: true,
+
+    balanceMicro: () => balanceOf(needProject()),
+    memberBalanceMicro: (accountRef) => {
+      if (!ACCOUNT_RE.test(String(accountRef))) throw new StripeError('bad account reference', { code: 'bad_account', refused: true });
+      return balanceOf(accountRef);
+    },
+
+    // Opened by us for that person: the metadata is written only by createMemberAccount below.
+    async confirmMemberAccount({ accountRef, builderId }) {
+      if (!ACCOUNT_RE.test(String(accountRef))) return false;
+      const a = await call('GET', `/v1/accounts/${accountRef}`);
+      const m = a.metadata || {};
+      return m.bongos_builder_id === String(builderId) && m.bongos_project === projectKey;
+    },
+
+    // The processor's hosted onboarding starts here: an Express account stamped with whose it is.
+    async createMemberAccount({ builderId, idempotencyKey }) {
+      const a = await call('POST', '/v1/accounts', {
+        idempotencyKey: idempotencyKey || `bongos-account-${projectKey}-${builderId}`,
+        params: { type: 'express', capabilities: { transfers: { requested: true } }, metadata: { bongos_builder_id: String(builderId), bongos_project: projectKey } },
+      });
+      return { ref: a.id };
+    },
+    async onboardingLink({ accountRef, returnUrl, refreshUrl }) {
+      for (const u of [returnUrl, refreshUrl]) {
+        const okUrl = allowedOrigin ? String(u).startsWith(`${allowedOrigin}/`) : /^https:\/\//.test(String(u));
+        if (!okUrl) throw new StripeError('Onboarding return addresses must be on the project own site.', { code: 'bad_return_url', refused: true });
+      }
+      const l = await call('POST', '/v1/account_links', { params: { account: accountRef, type: 'account_onboarding', return_url: returnUrl, refresh_url: refreshUrl } });
+      return { url: l.url };
+    },
+
+    async memberTransfer({ idempotencyKey, amountCents, currency, fromAccount, toAccount, toProject }) {
+      checkMoney({ amountCents, currency });
+      const dest = toProject ? needProject() : toAccount;
+      if (!ACCOUNT_RE.test(String(fromAccount)) || !ACCOUNT_RE.test(String(dest))) throw new StripeError('bad account reference', { code: 'bad_account', refused: true });
+      const t = await call('POST', '/v1/transfers', {
+        idempotencyKey, account: fromAccount,
+        params: { amount: amountCents, currency: CURRENCY, destination: dest, metadata: { bongos_key: idempotencyKey } },
+      });
+      return { ref: t.id };
+    },
+
+    async transfer({ idempotencyKey, amountCents, currency, builderId, payTo }) {
+      checkMoney({ amountCents, currency });
+      const dest = await payeeAccount({ builderId, payTo });
+      const t = await call('POST', '/v1/transfers', {
+        idempotencyKey, account: needProject(),
+        params: { amount: amountCents, currency: CURRENCY, destination: dest, metadata: { bongos_key: idempotencyKey } },
+      });
+      return { ref: t.id };
+    },
+
+    async memberPayout({ idempotencyKey, amountCents, currency, account, payTo = 'self' }) {
+      checkMoney({ amountCents, currency });
+      // A Stripe payout goes to the bank on the connected account itself. A 16-17 recipient's
+      // money must go to the guardian (payout-gates `pay_to`), which this call cannot do, so it
+      // is refused rather than paid to the wrong person. Nothing is sent.
+      if (payTo !== 'self') throw new StripeError('This payout must go to a guardian account, which a bank payout cannot do.', { code: 'guardian_payout_unsupported', refused: true });
+      if (!ACCOUNT_RE.test(String(account))) throw new StripeError('bad account reference', { code: 'bad_account', refused: true });
+      const p = await call('POST', '/v1/payouts', {
+        idempotencyKey, account,
+        params: { amount: amountCents, currency: CURRENCY, metadata: { bongos_key: idempotencyKey } },
+      });
+      return { ref: p.id, paid: p.status === 'paid' };
+    },
+
+    // ref is the PaymentIntent id of the buyer's charge. Figures come from Stripe, not the caller.
+    async readSale({ ref }) {
+      const p = await call('GET', `/v1/payment_intents/${encodeURIComponent(ref)}`);
+      if (p.status !== 'succeeded') throw new StripeError(`The sale ${ref} has not been paid.`, { code: 'sale_not_paid', refused: true });
+      return {
+        moduleKey: (p.metadata || {}).module_key,
+        priceCents: Number(p.amount),
+        platformFeeCents: p.application_fee_amount == null ? 0 : Number(p.application_fee_amount),
+        currency: String(p.currency || '').toUpperCase(),
+      };
+    },
+
+    // Compared with our record by object id (tr_, po_, py_…); the size of the movement, unsigned.
+    async listMovements({ since, until }) {
+      const account = needProject();
+      const out = [];
+      let after = null;
+      for (let page = 0; page < 50; page++) {
+        const r = await call('GET', '/v1/balance_transactions', {
+          account,
+          params: { limit: 100, 'created[gte]': Math.floor(new Date(since).getTime() / 1000), 'created[lt]': Math.ceil(new Date(until).getTime() / 1000), starting_after: after },
+        });
+        for (const t of r.data || []) {
+          if (t.currency !== CURRENCY || !t.source) continue;
+          out.push({ ref: typeof t.source === 'string' ? t.source : t.source.id, amountMicro: microOf(Math.abs(Number(t.amount))), createdAt: new Date(t.created * 1000).toISOString() });
+        }
+        if (!r.has_more || !(r.data || []).length) return out;
+        after = r.data[r.data.length - 1].id;
+      }
+      throw new StripeError('Too many movements to list in one check.', { code: 'too_many' });
+    },
+
+    // Webhook: verify Stripe's signature over the RAW body, then translate the payout news into
+    // the cash-out call. Returns { handled, outcome?, ref?, reason? }; throws on a bad signature.
+    verifyWebhook(rawBody, signatureHeader) {
+      if (!webhookSecret) throw new StripeError('No webhook secret is configured.', { code: 'no_webhook_secret' });
+      const parts = Object.fromEntries(String(signatureHeader || '').split(',').map((p) => p.split('=')).filter((p) => p.length === 2));
+      const t = Number(parts.t);
+      // a timestamp from the future is as suspect as an old one; replays inside the window are
+      // harmless only because recordProcessorOutcome repeats as a no-op (the route must keep that).
+      const age = now() / 1000 - t;
+      if (!Number.isFinite(t) || age > WEBHOOK_TOLERANCE_S || age < -60) throw new StripeError('Stale or missing webhook timestamp.', { code: 'bad_signature' });
+      const want = crypto.createHmac('sha256', webhookSecret).update(`${t}.${rawBody}`).digest('hex');
+      const ok = String(signatureHeader).split(',').some((p) => p.startsWith('v1=') && p.length === 3 + want.length
+        && crypto.timingSafeEqual(Buffer.from(p.slice(3)), Buffer.from(want)));
+      if (!ok) throw new StripeError('Webhook signature does not match.', { code: 'bad_signature' });
+      return JSON.parse(rawBody);
+    },
+    payoutNews(event) {
+      const o = event && event.data && event.data.object;
+      if (!o || !o.id) return { handled: false };
+      if (event.type === 'payout.paid') return { handled: true, outcome: 'paid', ref: o.id };
+      if (event.type === 'payout.failed') return { handled: true, outcome: 'returned', ref: o.id, reason: o.failure_message || o.failure_code || 'the bank returned this payout' };
+      return { handled: false };
+    },
+  };
+  return adapter;
+}
+
+// Built from the environment; null when no key is set (every flow then holds `no_processor`).
+function fromEnv(env = process.env, extra = {}) {
+  if (!env.STRIPE_SECRET_KEY) return null;
+  return createStripeProcessor({
+    secretKey: env.STRIPE_SECRET_KEY, projectAccount: env.STRIPE_PROJECT_ACCOUNT || null,
+    projectKey: env.STRIPE_PROJECT_KEY || env.STRIPE_PROJECT_ACCOUNT || 'project', allowedOrigin: env.STRIPE_ONBOARDING_ORIGIN || null,
+    webhookSecret: env.STRIPE_WEBHOOK_SECRET || null, ...extra,
+  });
+}
+
+module.exports = { createStripeProcessor, fromEnv, StripeError, encode };

package/modules/economy/routes/balances.js

@@ -31,6 +31,7 @@ function personalWebSession(req) {
 
 module.exports = function buildBalancesRouter({ processor = null } = {}) {
   const router = express.Router();
+  const proc = () => processor || api.resolveOptional('economy.processor');
 
   const fail = (res, err, what) => {
     if (err instanceof TransferRefusal) return res.fail(err.code, { status: err.status, message: err.message });
@@ -41,7 +42,7 @@ module.exports = function buildBalancesRouter({ processor = null } = {}) {
   // rank: any-builder — the signed-in person's own balance and their own payments.
   router.get('/balances/me', api.requireBuilder, async (req, res) => {
     try {
-      const out = await readMyBalance(api.pool, req.builder.id, { processor, limit: req.query.limit, log });
+      const out = await readMyBalance(api.pool, req.builder.id, { processor: proc(), limit: req.query.limit, log });
       res.set('Cache-Control', 'no-store');
       res.json(out);
     } catch (err) { fail(res, err, 'GET /balances/me'); }
@@ -50,7 +51,7 @@ module.exports = function buildBalancesRouter({ processor = null } = {}) {
   // rank: any-builder — the project's balance figure, so a member can see whether it needs funding.
   router.get('/balances/project', api.requireBuilder, async (req, res) => {
     try {
-      const out = await readProjectBalance({ processor, log });
+      const out = await readProjectBalance({ processor: proc(), log });
       res.set('Cache-Control', 'no-store');
       res.json(out);
     } catch (err) { fail(res, err, 'GET /balances/project'); }
@@ -65,7 +66,7 @@ module.exports = function buildBalancesRouter({ processor = null } = {}) {
       const out = await transfer({
         kind, fromBuilderId: String(req.builder.id), toBuilderId: b.to_builder_id,
         amountCents: b.amount_cents, instructionId: b.instruction_id, note: b.note,
-      }, { pool: api.pool, processor });
+      }, { pool: api.pool, processor: proc() });
       res.status(out.status === 'sent' ? 200 : 202).json(out);
     } catch (err) { fail(res, err, `POST /balances/${kind}`); }
   };

package/modules/economy/routes/project-account.js

@@ -18,6 +18,7 @@ const api = require('../../../src/module-api');
 const { readAccount, recordMovement, lockAccount, releaseSettledHolds, readAvailable } = require('../project-account');
 const { readOutflow } = require('../outflow');
 const { readLedgerChecks } = require('../ledger-check');
+const { fromEnv: stripeFromEnv } = require('../processor-stripe');
 const { memberAccount } = require('../user-balances');
 
 const log = api.logger('economy');
@@ -33,18 +34,28 @@ function registerSeams() {
   if (!api.hasProvider('economy.account')) {
     api.registerProvider('economy.account', { recordMovement, lockAccount, releaseSettledHolds, readAvailable, memberAccount });
   }
+  // The `economy.processor` PORT (task 1005040, ADR 0397): the Stripe Connect TEST-mode adapter,
+  // registered only when STRIPE_SECRET_KEY (an sk_test_ key) is set. With none, every flow holds
+  // `no_processor`, exactly as before. A bad key is logged and leaves the port unregistered.
+  if (!api.hasProvider('economy.processor')) {
+    try {
+      const adapter = stripeFromEnv(process.env, { memberAccountFor: (builderId) => memberAccount(api.pool, builderId) });
+      if (adapter) api.registerProvider('economy.processor', adapter);
+    } catch (e) { log.error({ err: e.message }, 'economy.processor not registered'); }
+  }
 }
 
 module.exports = function buildProjectAccountRouter({ processor = null } = {}) {
   registerSeams();
   const router = express.Router();
+  const proc = () => processor || api.resolveOptional('economy.processor');
 
   // rank: payout.approve (archon floor) — the owner. The account's balance and who was paid what
   // is the project's own money, so only the payout authority reads it (ADR 0016: enforced here, server-side).
   router.get('/project-account', api.requireBuilder, api.requirePermission('payout.approve'), async (req, res) => {
     try {
       const { limit, offset } = api.parsePagination(req, { defaultLimit: 50, maxLimit: 200 });
-      const out = await readAccount(api.pool, { limit, offset, processor, log });
+      const out = await readAccount(api.pool, { limit, offset, processor: proc(), log });
       res.set('Cache-Control', 'no-store');
       res.json({ ...out, page: api.pageMeta(limit, offset, out.movement_count) });
     } catch (err) {

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/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.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.24.96",
+      "version": "1.25.1",
       "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.1",
   "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,16 @@
       "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."
+    }
   ]
 }

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;