@bongos/core 1.24.96 → 1.25.2

package/docs/architecture.md

@@ -273,6 +273,8 @@ store_module_prices(id, module_key, price_cents, price_credits, set_by, set_at)
 
 Passkey foundation (migration `core_277`, task 1004750, [ADR 0382](adr/0382-a-hardware-card-is-a-passkey-step-up-an-archon-switches-on-per-builder.md) D1/D6 — storage only; the ceremonies and routes are their own tasks; code in `src/bongos/passkeys.js`):
 
+Card step-up gate (migration `core_298`, task 1004747, ADR 0382 D2/D5; code in `src/bongos/step-up.js`): `builders.require_card` (default false) + `builder_sessions.card_verified_at`, stamped only by `POST /me/passkeys/authenticate/verify`. `requireCardStepUp` (also `api.requireCardStepUp` for modules) refuses 403 `card_required` when the builder's flag is on and the session has no card tap in the last 10 minutes; it fails closed. Mounted on rank set, admin session revoke (the own-session panic button stays open), render-deploy act + PUT app, treasury pots/borrow answers. The Archon switch that sets the flag is task 1004748.
+
 ```
 passkey_credentials(id, credential_id UNIQUE, builder_id FK, public_key bytea, sign_count,
               transports[], aaguid, nickname, created_at, last_used_at)
@@ -322,7 +324,7 @@ payout_tax_details(id, builder_id, status collected|incomplete, collected_by pro
               -- POST /payouts/ndas, POST /payouts/tax-details (payout.approve + web session).
 ```
 
-Builder payouts (migration `core_290`, task 1003183, [ADR 0397](adr/0397-the-payment-rail-is-stripe-connect-with-one-connected-account-per-project.md) D7 — a builder is paid for a task exactly once; `src/bongos/builder-payouts.js`, routes `GET`/`POST /payouts/builder-payouts` gated `payout.approve` plus the person's own web session for the POST; the `payout` movement is booked through the economy module's `economy.account` port in the same transaction. No processor adapter exists yet, so every payout is recorded owed and held `no_processor`):
+Builder payouts (migration `core_298`, task 1003183, [ADR 0397](adr/0397-the-payment-rail-is-stripe-connect-with-one-connected-account-per-project.md) D7 — a builder is paid for a task exactly once; `src/bongos/builder-payouts.js`, routes `GET`/`POST /payouts/builder-payouts` gated `payout.approve` plus the person's own web session for the POST; the `payout` movement is booked through the economy module's `economy.account` port in the same transaction. No processor adapter exists yet, so every payout is recorded owed and held `no_processor`):
 
 ```
 builder_payouts_owed(id, builder_id FK, task_id FK, approval_id FK payout_approvals,

package/docs/copy-inventory.md

@@ -316,7 +316,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `4df46e2be815` | certain | Clear the key? | `modules/hall-ui/public/market-watch-settings.js:218` |
 | `593dda3178eb` | certain | Click to copy | `modules/hall-ui/public/copy-on-click.js:137` |
 | `34624d39ff29` | certain | Clone the project to your machine and run | `modules/hall-ui/public/setup-gate.js:34` |
-| `3a426bad2c49` | certain | Close actions | `modules/hall-ui/public/visor.js:293` |
+| `3a426bad2c49` | certain | Close actions | `modules/hall-ui/public/visor.js:336` |
 | `70f6a704d504` | certain | Close it | `modules/hall-ui/public/copy-desk.html:140` |
 | `053e576ba9a3` | certain | Close options | `modules/hall-ui/public/shell-game.js:454` |
 | `d12a2fb5730d` | certain | Close this flag | `modules/hall-ui/public/copy-desk.html:116` |
@@ -1486,7 +1486,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `9a685b01e2c6` | certain | This page opens at a higher rank. | `modules/hall-ui/public/watch.html:237` |
 | `e7a289134dc3` | certain | This page shows no words the reader could find. | `modules/hall-ui/public/tweak-editor.js:246` |
 | `d4b3b5556986` | certain | This page's reference docs | `modules/hall-ui/public/page-notes.js:166` |
-| `79e4a934b434` | certain | This place | `modules/hall-ui/public/visor.js:295` |
+| `79e4a934b434` | certain | This place | `modules/hall-ui/public/visor.js:338` |
 | `5bdcbec770dd` | certain | This project has no slash commands yet. | `modules/hall-ui/public/commands.js:37` |
 | `f53b83bfbe54` | certain | This project has no watch rules yet. | `modules/hall-ui/public/market-watch-rules.js:62` |
 | `e97b2d549f10` | certain | This project is hosted on {…}, and that is where it is taken offline or removed. Both links below open this pr | `modules/hall-ui/public/project-settings.js:412` |

package/docs/copy-registry.json

@@ -5208,7 +5208,7 @@
       "surface": "builders-hall",
       "text": "Close actions",
       "file": "modules/hall-ui/public/visor.js",
-      "line": 293,
+      "line": 336,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -15738,7 +15738,7 @@
       "surface": "builders-hall",
       "text": "This place",
       "file": "modules/hall-ui/public/visor.js",
-      "line": 295,
+      "line": 338,
       "origin": "js-markup",
       "confidence": "certain"
     },

package/docs/module-api-changelog.md

@@ -3440,5 +3440,11 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.24.94 with no explicit bump. run 43304959846. (task 1002620)
   1.24.96 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.24.95 with no explicit bump. run 43307125735. (task 1002620)
+  1.25.0 — adds `requireCardStepUp`, the hardware-card step-up gate a module mounts
+        after its permission gate (task 1004747, ADR 0382). Additive, so MINOR.
+  1.25.1 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.25.0 with no explicit bump. run 43313162829. (task 1002620)
+  1.25.2 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.25.1 with no explicit bump. run 43325008692. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/page-readings.json

@@ -283,7 +283,7 @@
       "surface": "builders",
       "title": "The city",
       "states_read": ["city","fullscreen","focus","pins","living","card","card-ask"],
-      "files_hash": "0367a0e57f2fcfb1",
+      "files_hash": "573bb0fbcdcafa9a",
       "reading_hash": "277096d903879a57",
       "counts": {"lines":26,"placed":9,"shared":6,"unplaced":11},
       "omitted": {"data":7},
@@ -613,7 +613,7 @@
       "surface": "builders",
       "title": "The sky",
       "states_read": ["tour","sky","wells","ledger","full","full-back","out"],
-      "files_hash": "9de2854d844d990f",
+      "files_hash": "fe5e504a7e12bca9",
       "reading_hash": "4a879397a84631e3",
       "counts": {"lines":50,"placed":25,"shared":6,"unplaced":19},
       "omitted": {"data":10},
@@ -954,8 +954,8 @@
       "surface": "builders",
       "title": "Builders' Hall",
       "states_read": ["home","out","founding","genesis","decide","demo"],
-      "files_hash": "36c7410d9c8aeae0",
-      "reading_hash": "45468116976bf674",
+      "files_hash": "b3b116e114d183f4",
+      "reading_hash": "59797028e6124c9c",
       "counts": {"lines":32,"placed":12,"shared":8,"unplaced":12},
       "omitted": {"data":5},
       "notes": ["founding: an action failed (page.focus: Timeout 6000ms exceeded.); read as it stood"],
@@ -977,7 +977,7 @@
         {"key":"L0015","section":"Needs your attention13","text":"Ideas awaiting triage","placement":"placed","file":"modules/hall-ui/public/builders.js","line":320,"string_id":"e181637c5a5e"},
         {"key":"L0016","section":"Needs your attention13","text":"Requires project {…} fix","placement":"unplaced"},
         {"key":"L0017","section":"footer","text":"Sign out","placement":"shared","file":"modules/hall-ui/public/shell.js","line":514,"string_id":"1883ad7f07fc"},
-        {"key":"L0018","section":"Needs your attention13","text":"core 1.24.94","placement":"unplaced"},
+        {"key":"L0018","section":"Needs your attention13","text":"core 1.25.1","placement":"unplaced"},
         {"key":"L0019","section":"Needs your attention13","text":"Skip","placement":"unplaced"},
         {"key":"L0020","section":"Needs your attention13","text":"Built on","placement":"placed","file":"modules/hall-ui/public/welcome-boot.js","line":183,"string_id":"fef59346ffee"},
         {"key":"L0021","section":"Needs your attention13","text":"cloudbongos.com","placement":"unplaced"},
@@ -3159,7 +3159,7 @@
       "surface": "builders",
       "title": "Your thinking",
       "states_read": ["tour","sky","list","simple","full-idea","full","full-list","full-back","out"],
-      "files_hash": "96c460b71d47125f",
+      "files_hash": "cd0f2d8f522becc8",
       "reading_hash": "b73f848b46b0f9b8",
       "counts": {"lines":50,"placed":25,"shared":6,"unplaced":19},
       "omitted": {"data":10},

package/migrations/core_298_card_step_up.sql

@@ -0,0 +1,16 @@
+-- core_298 card step-up: the per-builder requirement flag and the per-session proof
+-- Applied under task 1004747 (ADR 0382 D2, D4).
+--
+-- WHY. A builder who has a registered hardware card can be required to tap it before
+-- the sensitive actions (rank changes, deploy, session revoke, payouts). The server
+-- needs two things to keep: whether the requirement is on for a builder, and when a
+-- given session last proved a card.
+--
+--  * builders.require_card  default false: nothing changes for anybody until an
+--    Archon switches it on (that switch is its own task). Read fresh per request.
+--  * builder_sessions.card_verified_at  set ONLY by the card verify route, on the
+--    server-side session row. Nothing the client sends counts as proof, and a new
+--    session starts with none.
+
+ALTER TABLE builders         ADD COLUMN IF NOT EXISTS require_card boolean NOT NULL DEFAULT false;
+ALTER TABLE builder_sessions ADD COLUMN IF NOT EXISTS card_verified_at timestamptz;

package/modules/economy/module.json

@@ -8,6 +8,6 @@
   "default": true,
   "maintenance": { "status": "core-maintained" },
   "contributes": { "migrations": true, "routes": ["cost", "credits", "earnings", "leaderboard", "project-account", "balances", "reward"], "pollers": ["ledger-check"] },
-  "provides": ["reward", "economy.account"],
+  "provides": ["reward", "economy.account", "economy.processor"],
   "consumes": []
 }

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) {